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 and C# keep them in an immutable Core. 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

Assume the library detects none of this: a breach is undefined behaviour, not an error code.

• In C, initialize once. Call TA_Initialize once, and only once, per process, before any other TA call. Call TA_Shutdown before the process exits; the library must not be used after it. Rust, Java and C# have no lifecycle call: a Core is ready when constructed.
• In C, change a setting only while the library is idle. TA_SetUnstablePeriod, TA_SetCandleSettings and TA_RestoreCandleDefaultSettings change process-wide state: call them only while no TA function is running and no stream is open. TA_Shutdown counts as a change. Between changes, the library may be called from any number of threads (rT11); it allocates with malloc and free and assumes both are thread-safe.
• Give each stream handle one writer. Update, Advance and C's Close must not run concurrently with any other call on the same handle. 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 (C TA_ParamHolder, Java and C# ParamHolder) is not thread-safe, and in Java and C# neither is a CoreBuilder nor the caller-owned sink a Java multi-output stream writes into (Core.MacdOut for MACD). Make one per thread or per call. In C, the const in TA_CallFunc's signature does not make a holder shareable: the call writes the output buffers bound to it.

Managed cores

rT1 In Rust, Java and C#, settings live on an immutable Core made by a builder. 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()); the existing one is unchanged. A stream keeps the settings of the Core that opened it. A Java or C# builder stays usable after build(), and later changes to it never reach a Core it built.

Validation

The rows hold for every setter and getter in all four languages, except where a note says otherwise.

Rule	Condition	Language notes
rT2	A setter fails on a target outside its enum, and on the set-all wildcard when it takes a single target.	Rust and Java enums cannot hold an out-of-domain target, so only the wildcard fails there.
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.	C's TA_GetUnstablePeriod cannot fail: for the wildcard or an out-of-range id it returns 0, which is also a legal period. The getters on Core fail (failures): Rust get_unstable_period, Java unstablePeriod, C# UnstablePeriod and CandleSettings.
rT5	A candle setting's range type is a TA_RangeType member.	Checked in C and C#. Rust and Java cannot express another value.
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 builder latches the first failure until build(): a later valid setter or restore_candle_default does not clear it, and to_builder() starts with none latched.

rT9 A wildcard is legal where a call documents one. TA_FUNC_UNST_ALL (FuncUnstId::ALL, FuncUnstId.ALL) sets every unstable period at once. TA_AllCandleSettings restores every candle setting's default through TA_RestoreCandleDefaultSettings and the builders' restore call (restore_candle_default, restoreCandleDefault, RestoreCandleDefault). Elsewhere rT2 or rT4 applies.

rT12 A getter returns the value the setter stored. For an unstable period on an Auto level that is the level's constant, not a number of bars: the bars a level adds are read from the lookback (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.