Vector client C reference

The opaque types and observer declarations below come from the installed rbcVector.h. Observer functions are not entries in the public stubs table; external stub users must not assume they are available through that table. The final section contains private RBC helpers. See Vector ownership and notifications for storage, read-only state and notification reentry and client-data lifetime.

Types

typedef struct Rbc_Vector_s Rbc_Vector

Opaque vector record; access values and metadata through the API.

enum Rbc_VectorType

Storage element type; real and complex buffers are distinct.

Values:

enumerator RBC_VECTOR_REAL
enumerator RBC_VECTOR_COMPLEX
struct Rbc_Complex

Portable complex value, independent of native C complex support.

Public Members

double real

Real component.

double imag

Imaginary component.

typedef struct Rbc_VectorIdStruct *Rbc_VectorId

Observer token attached to one vector, not a vector reference count.

Survives vector rename. Free it when detaching, including from a callback. Vector destruction frees remaining tokens after delivering DESTROY; clients must discard their saved token at that point.

enum Rbc_VectorNotify

Client notification reason: changed data or imminent destruction.

Values:

enumerator RBC_VECTOR_NOTIFY_UPDATE
enumerator RBC_VECTOR_NOTIFY_DESTROY

Callback signature (included verbatim to retain Tcl’s function-typedef syntax):

typedef void(Rbc_VectorChangedProc)(Tcl_Interp *interp, ClientData clientData, Rbc_VectorNotify notify);
Notification callback arguments

Parameter

Contract

interp

Borrowed owning interpreter; see interpreter arguments.

clientData

Caller-owned registration data, never freed or preserved by RBC. The observer’s owner must keep it valid through nested callbacks.

notify

UPDATE announces changed values; DESTROY announces teardown. During DESTROY, discard the token and borrowed vector views. Remaining tokens are freed by RBC after delivery.

Use Rbc_SetVectorChangedProc() to install or disable the callback, and Rbc_FreeVectorId() to detach an observer. A token observes an identity; it is not a preservation reference. For ranged updates, the private Rbc_VectorGetChangedRange() reports the current callback’s snapshot.

Callbacks borrow their data and must obey the lifetime and reentry restrictions in Vector ownership and notifications.

Observers and range access

Rbc_VectorId Rbc_AllocVectorId(Tcl_Interp *interp, const char *vecName)

Register an observer of an existing vector without copying its values.

See also

Rbc_FreeVectorId

Parameters:
  • interp – [in] Interpreter containing the vector registry. See Interpreter arguments.

  • vecName – [in] Borrowed name resolved by the vector name lookup rules.

Returns:

New token, initially without a callback, or NULL with a diagnostic.

void Rbc_FreeVectorId(Rbc_VectorId clientId)

Detach an observer, deferring reclamation while delivery retains it.

Does not destroy the vector. May be called from UPDATE or DESTROY callbacks. Destruction itself frees remaining IDs. A magic-field check is not permission to pass freed or arbitrary pointers. NULL is accepted.

Parameters:
  • clientId – [in] Allocated token, or NULL; invalid after this call.

int Rbc_GetVectorById(Tcl_Interp *interp, Rbc_VectorId clientId, Rbc_Vector **vecPtrPtr)

Borrow the vector associated with a client ID and refresh its range.

Neither the returned pointer nor the ID extends vector lifetime. Never call this with a token left over after vector destruction. Cached extrema are recomputed when invalidated; this is not always a constant-time lookup.

Parameters:
  • interp – [in] Interpreter used for error reporting. See Interpreter arguments.

  • clientId – [in] Non-NULL live token.

  • vecPtrPtr – [out] Receives the borrowed vector on success only.

Returns:

TCL_OK, or TCL_ERROR with a diagnostic for a bad/disconnected token.

void Rbc_SetVectorChangedProc(Rbc_VectorId clientId, Rbc_VectorChangedProc *proc, ClientData clientData)

Replace an observer’s callback and borrowed callback data.

Does not invoke the callback immediately or transfer ownership of clientData.

Parameters:
  • clientId – [in] Non-NULL live token.

  • proc – [in] Callback, or NULL to disable calls without detaching the ID.

  • clientData – [in] Borrowed data passed to proc; never freed by RBC.

char *Rbc_NameOfVectorId(Rbc_VectorId clientId)

Return the vector’s current registered name, not its array mapping.

Do not modify or free the returned string. Copy it if it must survive rename. A token already freed by destruction cannot be queried.

Parameters:
  • clientId – [in] Non-NULL live token.

Returns:

Borrowed name until rename/destruction, or NULL if disconnected.

int Rbc_VectorNotifyPending(Rbc_VectorId clientId)

Test whether an idle update notification is queued.

The nonzero result is a flag mask, not necessarily 1. It is not a test for all possible data changes, and cannot validate a freed token.

Parameters:
  • clientId – [in] Live token, or NULL.

Returns:

Nonzero for a pending notification; zero for NULL/disconnected IDs.

int Rbc_VectorGetRange(Rbc_Vector *vecPtr, double *minPtr, double *maxPtr)

Get cached finite extrema of a real vector, recomputing if necessary.

Read cached finite extrema of a real vector.

Empty vectors and vectors without finite values return NaN extrema.

Get cached finite extrema of a real vector, recomputing if necessary.

Requires a live vector and two non-NULL output pointers. Returns TCL_ERROR for complex vectors without changing outputs. Recomputes whole-vector extrema only when UPDATE_RANGE is set, otherwise uses the cache. Empty or entirely nonfinite real vectors return TCL_OK with NaN bounds. Does not use the current selection, flush mapped arrays or notify observers.

Parameters:
  • vecPtr – [inout] Live borrowed vector; its extrema cache may be updated.

  • minPtr – [out] Receives minimum on success; must not be NULL.

  • maxPtr – [out] Receives maximum on success; must not be NULL.

Returns:

TCL_OK for a real vector; TCL_ERROR for complex storage, without an interpreter diagnostic or changes to the output parameters.

Private update helpers

void Rbc_VectorUpdateClients(VectorObject *vPtr)

Invalidate extrema and report a full/unknown data change internally.

Invalidate global extrema and schedule a full update.

Increments the dirty counter and follows the vector’s notification policy. Immediate policy invokes callbacks before return. Does not flush the mapped Tcl array cache or check read-only state; mutation code owns those steps.

Invalidate extrema and report a full/unknown data change internally.

Requires a live vector record. Invalidates cached bounds and their indices before delegating to the notification scheduler. Does not alter storage, check writability or flush mapped arrays. Immediate notification may execute callbacks and destroy the vector before return; callers needing further access must preserve and revalidate it.

Parameters:
  • vPtr – [inout] Live vector, already modified by the caller.

void Rbc_VectorUpdateClientsRange(VectorObject *vPtr, Tcl_Size first, Tcl_Size last)

Report changed existing storage using inclusive zero-based indices.

Publish an inclusive changed interval with incremental extrema maintenance.

Invalid intervals become full updates. Valid intervals coalesce until delivery; real extrema are maintained incrementally when possible. Does not change length/ownership, flush array caches or enforce read-only state.

Report changed existing storage using inclusive zero-based indices.

Requires a live vector whose caller has already changed only the stated storage interval. Invalid or reversed bounds delegate to a full update. Valid real intervals update cached extrema when untouched old extrema suffice, otherwise invalidate the cache for a later full scan. Schedules a ranged notification for valid intervals, including complex vectors. Does not enforce writability, change storage or flush arrays. Immediate callbacks may destroy the vector; no vector access follows scheduling.

Parameters:
  • vPtr – [inout] Live vector, already modified in place.

  • first – [in] First changed storage index, independent of Tcl index offset.

  • last – [in] Last changed storage index, inclusive.

int Rbc_VectorGetChangedRange(Rbc_VectorId clientId, Tcl_Size *firstPtr, Tcl_Size *lastPtr)

Read the interval snapshot during this client’s UPDATE callback.

Coalescing may include unchanged values between separate modified intervals. This helper is private and has no public stub entry.

Parameters:
  • clientId – [in] Live observer token, or NULL.

  • firstPtr – [out] Optional first inclusive zero-based index.

  • lastPtr – [out] Optional last inclusive zero-based index.

Returns:

TRUE if a range is available; FALSE for a full/unknown update, DESTROY, outside delivery, or a NULL/disconnected token. Outputs are left unchanged on FALSE. Never pass a token freed by vector destruction.