Settings and Threads

Part of TA-Lib's specification, a reference for AI-agent-driven integration.

C keeps its settings (unstable periods and candle settings) process-wide; Rust, Java, C# and TypeScript keep them in an immutable Core, so cores with different settings coexist in one process, and in Rust, Java and C# any number of threads can share one with no synchronization (rT1). What each setting means: Unstable Period, Candlestick Settings (with the defaults). Names per language: names. How a failure reaches the caller: failures.

The caller must

In C, initialize exactly once per process. Call TA_Initialize before any other TA call. Call TA_Shutdown before the process exits; the library must not be used after it. Rust, Java, C# and TypeScript have no lifecycle call: a Core is ready when constructed.
In C, change a setting only while no TA function is running and no stream is open. A change is a call to TA_SetUnstablePeriod, TA_SetCandleSettings, TA_RestoreCandleDefaultSettings or TA_Shutdown. Between changes, any number of threads may call the library (rT11); it assumes the malloc and free it allocates with are thread-safe.
Run a writer alone on its stream handle. The writers are Update, Advance and C's Close; not even Peek or Value may run alongside one. Separate handles, a clone included (rH8), may each be driven on their own thread. Rust enforces this at compile time: the writing calls take &mut self, and every handle is Send + Sync + Clone.
Confine holders, builders and sinks to one thread. A parameter holder is not thread-safe in C, Java and C#; neither is a Java or C# CoreBuilder nor the sink a Java multi-output stream writes into (names). In C, the const in TA_CallFunc's signature does not make a holder shareable: the call writes the output buffers bound to it.

`Core` in Rust, Java, C# and TypeScript

rT1 In Rust, Java, C# and TypeScript, settings live on an immutable Core made by a builder. In Rust, Java and C#, one Core may be shared by any number of threads with no synchronization; Rust's is Send + Sync. To change a setting, build another Core, from defaults or seeded from an existing one (to_builder(), toBuilder(), ToBuilder()). A stream keeps the settings of the Core that opened it. A Java, C# or TypeScript builder stays usable after build().

Validation

The rows hold for every setter and getter in every language, except where a note says otherwise. A Rust or Java enum cannot hold a value outside its members.

Rule	Condition	Language notes
rT2	A setter fails on a target outside its enum. `TA_SetCandleSettings` and the builders' candle setter also fail on `TA_AllCandleSettings`.	In Rust and Java only the wildcard fails.
rT3	An unstable period is a count in `[0, TA_INDEX_MAX]` or an Auto level: `TA_UNSTABLE_AUTO_PREC_4` or `TA_UNSTABLE_AUTO_PREC_8` (constants).	C takes an `unsigned int`, so a negative value arrives above every level and fails. Rust's `u32` cannot hold one.
rT4	Reading a setting for the set-all wildcard fails.	For the wildcard or an out-of-range id, C's `TA_GetUnstablePeriod` returns 0, which is also a legal period.
rT5	A candle setting's range type is a `TA_RangeType` member.
rT6	A candle setting's `avgPeriod` is in `[0, TA_INDEX_MAX]`.
rT7	A candle setting's `factor` is finite and not negative.
rT8	A failed call leaves every setting as it was, a wildcard call included.	Rust's `build()` returns the first failure, even after a later valid setter or `restore_candle_default`.

rT9 Two wildcards act on every member at once: TA_FUNC_UNST_ALL sets every unstable period, and TA_AllCandleSettings restores every candle setting's default through TA_RestoreCandleDefaultSettings and the builders' restore call (restore_candle_default, restoreCandleDefault, RestoreCandleDefault).

rT12 A getter returns the value the setter stored. For an unstable period on an Auto level that is the level's constant, not the number of bars it adds (rL6).

Initial state

rT10 In C, TA_Initialize leaves every unstable period at 0 and every candle setting at its default.

Threads in C

rT11 Between setting changes, C calls made from several threads at once, each on its own stream handles and parameter holders, return what a single thread returns. On one handle with no writer running, Peek, Value, OutRange and Clone may run from several threads at once.