Streaming

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

A stream is defined as the batch call over every bar fed to it: the same values, bit for bit, and the same range (rH1); a bar counted with Advance is in the range but not in the computation.

Every function streams (rH9): Open or OpenAndFill once, then Update per closed bar and Peek per forming bar; Value, OutRange, Advance and Clone at any time; Close in C only. Calls, examples and per-language shapes: C/C++, Rust, Java, C#. Rules use C's verbs (TA_<N>_Open and so on); each language's spelling is in names, and how each code reaches the caller in failures.

The caller must

Open on at least lookback + 1 finite bars. A shorter, non-empty history returns TA_INSUFFICIENT_HISTORY (rS8), the one recoverable code: send more bars rather than fix the call.- Account for every rejected bar. A rejected Update changed nothing (rH5), so the handle is now one bar behind the feed. Re-feed the bar with a corrected value, or count it with Advance (rH6).
In C, close every handle exactly once. Open, OpenAndFill and Clone each return a handle that Close frees. Never open or clone into a variable that holds a live handle: a failed call sets it to NULL. Rust drops a handle; Java and C# collect it.
Keep the bars to resume. A handle is not serializable and is valid only within the library version that opened it. To restart, reopen on the bars, then call Advance once for each bar the old handle counted without being fed (rH6).
Give each handle one writer: threads. In C, change no setting while a stream is open: settings.

Definition

rH1 Open a stream on bars 0 to k, then Update it with bars k+1 to t, with no Advance. At every bar the stream reported (Open's value for bar k, each Update's for its bar), the value is bit-identical to what batch(0, t) writes for that bar, and OutRange equals the range batch(0, t) reports. This holds under the same parameters and settings. Exceptions: a zero output may differ in sign, +0.0 against -0.0, which compare equal; and a value that depends on a transcendental function may differ in the last bits (transcendental functions).

rH2 The history given to Open defines bar 0. State is carried forward from bar to bar and never re-seeded, so a stream opened on a later start equals the batch call over that shorter series. Which functions' values depend on the start: /functions/stability.

Opening

For Open and OpenAndFill, the history is the first declared input and historyLen its length (a C argument).

Rule	Condition	Code	Not checked in
rS1	The history is empty (`historyLen < 1`)	`TA_OUT_OF_RANGE_START_INDEX`
rS2	The history holds more than `TA_INDEX_MAX + 1` bars	`TA_OUT_OF_RANGE_END_INDEX`
rS3	As rB3	`TA_BAD_PARAM`
rS4	A required argument is absent (rB4): an input, an output, or in C the handle out-parameter, `outBegIdx` or `outNBElement`	`TA_BAD_PARAM`
rS5	An input's length differs from `historyLen`, or an `OpenAndFill` output holds fewer than `historyLen - lookback` values	`TA_BAD_PARAM`	C: cannot check (input length)
rS6	`OpenAndFill`: an output is the buffer of an input or of another output	`TA_BAD_PARAM`	Rust: cannot alias
rS7	`OpenAndFill`: an output that is not declinable is declined (rW5)	`TA_BAD_PARAM`	Rust: cannot decline
rS8	The history holds at least one bar, but fewer than lookback `+ 1`	`TA_INSUFFICIENT_HISTORY`

A loop that waits for enough history may open on one bar: a short history is rS8, an empty one rS1.

rH3 OpenAndFill writes what batch(0, historyLen - 1) writes, compared as in rH1: historyLen - lookback values per output from index 0, the first for bar lookback, and the same range. It takes no startIdx. The handle it returns then updates as the one Open returns on the same history.

Advancing

Update and Peek take a bar; Advance counts one that was not fed.

Rule	Condition	Code	Calls	Not checked in
rU1	The handle is absent	`TA_BAD_PARAM`	every handle call except Close	Rust, Java, C#: cannot be absent
rU2	A required output is absent: a C out-pointer, a Java multi-output sink	`TA_BAD_PARAM`	Update, Peek; in C also Value, OutRange, Clone	Rust, C#: value returned
rU3	A bar value is NaN, `+Inf` or `-Inf`	`TA_BAD_PARAM`	Update, Peek
rU4	The bar this call would count leaves the index domain: `begIdx + count > TA_INDEX_MAX`	`TA_OUT_OF_RANGE_END_INDEX`	Update, Advance
rU5	An output that is not declinable is declined (rW5)	`TA_BAD_PARAM`	Update, Peek	Rust, Java, C#: nothing to decline

rU4 never clears: open a new handle on a shorter history. Peek counts no bar, so it still succeeds at the ceiling.
In C, a decline applies to that call alone: the outputs an Update or Peek declines may differ from the opener's and from the previous call's.
An accepted bar whose output is not finite (rW6) is a success: the call returns that value and the bar is counted.

rH4 Peek never advances the stream and never changes the handle, however often it is called. Its value is bit-identical to what the next Update with the same bar returns.

rH5 A rejected Update or Peek changes nothing: no state, no value, no range, no output variable written. A re-fed bar counts exactly once. An allocation failure (rB8) or an internal error (rB9) is outside this rule.

rH6 Advance counts one bar the handle was not fed: the range grows by one, and that bar's output is the previous one, held. Later Updates compute over the bars fed, as if the counted bar did not exist; only the range includes it. An index output (rW4) is a position among the bars fed: a bar fed after k Advance calls has an index k less than its place in OutRange.

Accessors

rH7 Value returns the value(s) at the last counted bar, the bar the range ends on: after Open the last history bar's, after an accepted Update that bar's, after Advance the held value. OutRange is [begIdx, begIdx + count) in the input series' coordinates: the batch range over the same bars, Advance-counted bars included. The range stays within the index domain (rU4).

rH8 Clone is a deep, independent fork at the same bar: the same value and range, and updating either never affects the other.

Discovery

rH9 Every function streams, in every language. The metadata flag is TA_FUNC_FLG_STREAM: Rust FuncFlags::STREAM, Java FuncFlags.STREAMING, C# FuncFlags.Stream. A stream is opened by its typed Open; the Abstract API binds batch calls only.

Release

rH10 In C, Close(NULL) succeeds and does nothing. Rust, Java and C# have no release call.