Vector storage public C reference
These functions are public entries in generic/rbc.decls. Their contracts come from the reviewed implementations in
rbcVector.c. See Vector C API and storage primitives for ownership, units, creation reuse and remaining callback restrictions; see
Vector client C reference for observers and extrema.
- group Vector storage public C API
Reviewed stubs-facing lifetime, storage and protection contracts.
Functions
-
int Rbc_VectorExists2(Tcl_Interp *interp, const char *vecName)
Test whether a literal registered vector name exists.
Searches the current/global namespace rules without parsing a vector range. Returns a boolean; accepts an interpreter and name, not an observer token. May lazily initialize interpreter vector data. Does not retain a found vector.
- Parameters:
interp – [in] See Interpreter arguments; uses its vector registry.
vecName – [in] Borrowed literal name, resolved in the current/global namespaces.
- Returns:
Nonzero if found, zero otherwise; no ownership is acquired.
-
int Rbc_GetVector(Tcl_Interp *interp, const char *name, Rbc_Vector **vecPtrPtr)
Resolve a vector reference into a borrowed C vector pointer.
Returns TCL_OK and writes vecPtrPtr on success; reports lookup failure with TCL_ERROR. Allows range syntax, updates the shared first/last selection and refreshes invalid cached extrema. Index expressions may execute Tcl. The result is the original vector identity, not a slice or ownership reference; callers must manage lifetime before using it across subsequent evaluation.
- Parameters:
interp – [in] See Interpreter arguments; index expressions may execute Tcl.
name – [in] Borrowed vector reference, optionally including a range.
vecPtrPtr – [out] Required pointer receiving the borrowed identity on success; unchanged on error.
- Returns:
TCL_OK on lookup success; TCL_ERROR with a diagnostic otherwise.
-
int Rbc_CreateVector(Tcl_Interp *interp, const char *name, Tcl_Size size, Rbc_Vector **vecPtrPtr)
Create or reuse a real vector through the typed creation interface.
Delegates to Rbc_CreateVectorWithType with RBC_VECTOR_REAL. Returns a Tcl status and optionally a borrowed vector pointer. Existing same-type writable vectors may be reused; this is not a create-only operation.
- Parameters:
interp – [in] See Interpreter arguments.
name – [in] Borrowed requested name; #auto requests a generated name.
size – [in] Nonnegative initial length in values; zero retains an existing length.
vecPtrPtr – [out] Optional borrowed identity output; unchanged on error.
- Returns:
Tcl creation status; callback side effects are not rolled back.
-
int Rbc_CreateVectorWithType(Tcl_Interp *interp, const char *name, Tcl_Size size, Rbc_VectorType type, Rbc_Vector **vecPtrPtr)
Create or reuse a typed vector with its same-named Tcl command.
Real names without an opening parenthesis request a same-named mapped array; complex names and real names containing parentheses do not. Delegates to Rbc_CreateVector2. Type must be real or complex. A zero requested size does not clear an existing vector. Returns a Tcl status; output ownership and callback handling are those of the underlying creation helpers.
- Parameters:
interp – [in] See Interpreter arguments.
name – [in] Borrowed requested name; #auto requests a generated name.
size – [in] Nonnegative initial length in values; zero retains an existing length.
type – [in] RBC_VECTOR_REAL or RBC_VECTOR_COMPLEX; reused vectors must match.
vecPtrPtr – [out] Optional borrowed identity output; unchanged on error.
- Returns:
Tcl creation status; callback side effects are not rolled back.
-
int Rbc_ResizeVector(Rbc_Vector *vecPtr, Tcl_Size length)
Resize a live vector and publish a full change.
Delegates to Rbc_VectorChangeLength, flushes when configured and reports a full update. On resize error replaces the message with a generic resize error unless the identity was destroyed. Retains the record and interpreter across custom release and publication. May invalidate borrowed storage; success does not promise that a later publication callback left the vector alive.
- Parameters:
vecPtr – [inout] Live borrowed destination; must be writable.
length – [in] Nonnegative requested length in values, subject to allocation limits.
- Returns:
Tcl resize status; success does not guarantee survival of notification callbacks.
-
char *Rbc_NameOfVector(Rbc_Vector *vecPtr)
Return the borrowed current registered name.
Valid until rename or destruction; copy it if needed across either operation. Requires a live registered vector. Does not allocate, retain or change it.
- Parameters:
vecPtr – [in] Live borrowed registered vector.
- Returns:
Borrowed registered name, invalidated by rename or destruction.
-
int Rbc_ResetComplexVector(Rbc_Vector *vecPtr, Rbc_Complex *valueArr, Tcl_Size length, Tcl_Size size, Tcl_FreeProc *freeProc)
Replace the storage contract of a complex vector.
Rejects real vectors, then delegates to ResetVectorStorage. Length/capacity count complex values, not components or bytes. Honors static, dynamic, volatile and custom ownership policies; publishes a full change on success. Returns a Tcl status with the ownership-commit semantics of ResetVectorStorage.
- Parameters:
vecPtr – [inout] Live writable destination of the matching numeric type.
valueArr – [in] Storage to copy, borrow or adopt according to freeProc; NULL requests empty storage.
length – [in] Nonnegative used value count; must not exceed size.
size – [in] Nonnegative capacity in values, not bytes; zero requests empty storage.
freeProc – [in] TCL_STATIC borrows, TCL_DYNAMIC adopts Tcl storage, TCL_VOLATILE copies; otherwise a custom release callback. Ownership transfers only on successful acceptance.
- Returns:
TCL_OK once the storage contract is accepted; TCL_ERROR before acceptance.
-
int Rbc_ResetVector(Rbc_Vector *vecPtr, double *valueArr, Tcl_Size length, Tcl_Size size, Tcl_FreeProc *freeProc)
Replace the storage contract of a real vector.
Delegates to Rbc_VectorReset and ResetVectorStorage. Length/capacity count doubles. Use Rbc_VectorChanged instead for an in-place write with unchanged length and ownership. Returns a Tcl status; ownership transfer and release/cache callback handling follow the shared storage-reset implementation.
- Parameters:
vecPtr – [inout] Live writable destination of the matching numeric type.
valueArr – [in] Storage to copy, borrow or adopt according to freeProc; NULL requests empty storage.
length – [in] Nonnegative used value count; must not exceed size.
size – [in] Nonnegative capacity in values, not bytes; zero requests empty storage.
freeProc – [in] TCL_STATIC borrows, TCL_DYNAMIC adopts Tcl storage, TCL_VOLATILE copies; otherwise a custom release callback. Ownership transfers only on successful acceptance.
- Returns:
TCL_OK once the storage contract is accepted; TCL_ERROR before acceptance.
-
int Rbc_VectorIsReadOnly(Rbc_Vector *vecPtr)
Return the current data-protection flag.
Requires a live vector. Does not protect ownership/lifetime or intercept native pointer writes. No notification, allocation or Tcl evaluation occurs.
- Parameters:
vecPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Current boolean data-protection state.
-
int Rbc_VectorSetReadOnly(Tcl_Interp *interp, Rbc_Vector *vecPtr, int readOnly)
Set reversible data protection without publishing a value change.
Normalizes any nonzero argument to true and returns TCL_OK. The interpreter argument is unused. Requires a live vector; does not alter storage, type, identity, clients or lifetime ownership.
- Parameters:
interp – [in] Unused here; see Interpreter arguments.
vecPtr – [inout] Live borrowed vector whose protection flag is changed.
readOnly – [in] Zero unlocks; any nonzero value locks data writes.
- Returns:
TCL_OK; no notification is emitted.
-
int Rbc_VectorCheckWritable(Tcl_Interp *interp, Rbc_Vector *vecPtr)
Reject a protected destination before writing through the C API.
Returns TCL_OK when writable, or TCL_ERROR with RBC VECTOR READONLY and a name-bearing message. Requires a live record; it is not a destroyed-pointer validator. Native producers must call it before direct writes and recheck after callbacks that could change protection. Does not undo a prior write.
- Parameters:
interp – [in] See Interpreter arguments; receives the protection diagnostic.
vecPtr – [in] Borrowed valid vector record; not an arbitrary-pointer validator.
- Returns:
TCL_OK if writable; TCL_ERROR for a destroyed or protected record.
-
void Rbc_VectorChanged(Rbc_Vector *vecPtr)
Publish a full change after an in-place native write.
Flushes the mapped cache when configured, then invalidates extrema and follows the notification policy. Does not check writability, replace storage or change length. The caller checks before writing. Retains the record and interpreter, preserves interpreter result state and skips notification if flushing destroys the identity. A same-named replacement is never used as the notification target.
- Parameters:
vecPtr – [inout] Borrowed live vector after a completed writable in-place update.
-
void Rbc_VectorChangedRange(Rbc_Vector *vecPtr, Tcl_Size first, Tcl_Size last)
Publish an inclusive changed interval of existing storage.
Indices are zero-based storage positions, independent of external offset. Invalid intervals conservatively become full updates. Storage ownership and length must remain unchanged. Flushes before ranged notification and does not check writability; shares Rbc_VectorChanged lifetime restrictions.
- Parameters:
vecPtr – [inout] Borrowed live vector after completed in-place writes.
first – [in] First changed zero-based storage index, inclusive.
last – [in] Last changed zero-based storage index, inclusive; invalid intervals force a full update.
-
void Rbc_FreeVector(Rbc_Vector *v)
Destroy a vector identity through the private destruction implementation.
Delegates to Rbc_VectorFree, including synchronous DESTROY notification and custom storage release. Requires a live non-NULL pointer; read-only state does not block destruction. All borrowed storage/name pointers and observer IDs become unusable according to the destruction contract.
- Parameters:
v – [in] Live non-NULL identity to destroy; all borrowed views become invalid.
-
Rbc_Complex *Rbc_VectorComplexData(Rbc_Vector *vPtr)
Borrow the complex storage pointer, or return NULL for a real vector.
Requires a live record. NULL may also denote empty complex storage. Length and capacity count pairs. Reacquire after storage replacement or callbacks; check writability before native writes and publish changes afterward.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Borrowed complex buffer, or NULL for a real vector or empty storage.
-
double *Rbc_VectorData(Rbc_Vector *vPtr)
Borrow the real storage pointer, or return NULL for a complex vector.
Requires a live record. NULL may also denote empty real storage. Does not retain the record or buffer. Reacquire after storage replacement or callbacks; check writability before native writes and publish changes afterward.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Borrowed real buffer, or NULL for a complex vector or empty storage.
-
Tcl_Size Rbc_VectorLength(Rbc_Vector *vPtr)
Return the number of used values in a live vector.
Real and complex vectors both count values, not bytes. Does not refresh extrema, retain storage or evaluate Tcl.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Used value count, including complex pairs as single values.
-
Tcl_Size Rbc_VectorSize(Rbc_Vector *vPtr)
Return allocated capacity in values, not the used length or bytes.
Requires a live vector. Real capacity counts doubles; complex capacity counts Rbc_Complex values. Capacity is an implementation/storage contract detail and may change on resize or reset.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Allocated capacity in values.
-
int Rbc_VectorDirty(Rbc_Vector *vPtr)
Return the current modification counter from a live vector.
Returns an int counter, not a boolean or pending-notification flag. Internal update scheduling increments it even when ordinary notifications are disabled. Direct unreported pointer writes do not increment it. Does not clear it.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
Modification counter; reading it does not reset it.
-
Rbc_VectorType Rbc_VectorGetType(Rbc_Vector *vPtr)
Return the immutable real/complex type of a live vector.
Does not inspect contents, convert storage, retain the record or evaluate Tcl.
- Parameters:
vPtr – [in] Live borrowed vector; NULL is not accepted.
- Returns:
RBC_VECTOR_REAL or RBC_VECTOR_COMPLEX.
-
int Rbc_VectorExists2(Tcl_Interp *interp, const char *vecName)