Package loading and stubs
The package index, generic/rbcInt.c and generic/rbcStubLib.c divide loading into Tcl-only initialization, Tk
command registration and client-side C API setup. See Package initialization C reference for public interfaces and private
helper contracts.
Loader sequence
pkgIndex.tcl.in chooses the Tcl 9 or Tcl 8 library filename from the running Tcl version and registers three package
scripts:
Package |
Loading work |
|---|---|
|
Loads the shared library with entry-point prefix |
|
Requires the exact matching vector package and Tk, invokes |
|
Requires the exact matching full package, sources |
The toolbar script prefers installed argparse and uses the bundled Tcl-only copy when argparse is missing. Full RBC loading does not source the toolbar. The legacy graph helpers remain part of full loading for compatibility.
A direct load of the binary establishes the vector package only. Embedders needing widgets and their Tcl support
scripts should require rbc rather than treating successful binary loading as full initialization. The private
_initTk command is a loader step, not a replacement public loading API.
Interpreter state and registration
RbcInitData is associated with the interpreter under rbc::init. Its five
flags record completed vector, graph, winop, spline and EPS initialization.
FreeInitData frees this bookkeeping record at interpreter teardown; it does
not own every object created by those subsystems.
Rbc_Init() creates ::rbc if needed, initializes the vector subsystem once, creates ::rbc::_initTk and
exports vector. Vector initialization creates both ::rbc::vector and ::rbc::vector::simplify. Its registry,
numerical function tables and vector cleanup belong to a separate interpreter-associated VectorInterpData
record; see Vector ownership and notifications.
_initTk first initializes Tk stubs, then registers the graph constructors, winop and spline commands, followed by
the EPS canvas item. It exports barchart, graph, polar, spline, stripchart, trackgraph and
winop. Graph registration installs component UIDs and constructor commands; it does not create a graph window. Each
later constructor owns its widget instance; see Graph lifecycle and redisplay.
Flags are per interpreter, even though the shared library is loaded once in a process. They do not make vectors transferable between interpreters, and do not turn process-global stubs pointers or Tk services into thread-safe interfaces. Use vector and widget objects in their owning interpreter and thread.
Failure boundaries
Each successful phase sets its readiness flag before the next phase runs. A later error leaves earlier commands and flags in place. A retry skips those completed phases; initialization is not one rollback transaction. These flags also do not detect or recreate commands deliberately removed after loading.
The C Tk initializer provides rbc before the package script sources its Tcl files. A sourcing error can therefore
leave native commands and the provided package record installed even though the support script did not finish. Loading
code must report that error; checking only package provide rbc is not proof that every support script
completed. This is an existing boundary, not a guarantee of automatic recovery on a subsequent require.
Client stubs and ABI maintenance
A consumer links the RBC stub library and calls Rbc_VectorInitStubs() for Tcl-only vector access or
Rbc_InitStubs() when it needs the full package. Both use Tcl_PkgRequireEx and assign its client data to the
consumer’s rbcStubsPtr. Both packages publish the same table from rbcStubInit.c. Successful initialization
selects functions; it does not own vectors or retain the interpreter. See Vector client C reference for storage ownership
and read-only checks.
The pointer belongs to the linked stub object, not to each interpreter. A failed initialization leaves its previous
value unchanged. Consumers must check the return value rather than use a previously non-NULL pointer as evidence
that loading succeeded in another interpreter. The helpers do not validate the table magic or individual slots; a
NULL package client-data pointer returns NULL without adding its own diagnostic.
generic/rbc.decls defines numbered public slots. rbcDecls.h supplies the table type, declarations and client
dispatch macros; rbcStubInit.c supplies the implementation addresses. Preserve existing slot numbers and signatures
when extending the ABI, and update generated sections through tools/genStubs.tcl. Require a package version
containing every slot used by a consumer. Private renderer or graph declarations do not become public APIs merely by
being documented; see Header structure and Implementation overview.
Loader callbacks versus package initialization
On Windows, DllMain accepts every loader notification and
DllEntryPoint simply forwards to it. Neither performs
registration, allocation or subsystem cleanup. Loading the DLL and initializing its Tcl package are distinct steps;
none of the per-interpreter readiness flags is set by the native loader callbacks.
InitTkObjCmd assumes that Rbc_Init() has already installed the
associated record and namespace. It checks arity before Tk initialization. Readiness flags guard registration phases
only: namespace exports and package provision still run on a later call even when all subsystem flags are set. EPS
registration is marked complete after its void initializer returns, unlike phases with a Tcl status. Deleting
associated data or manually reconstructing this private command is not a supported reset mechanism.
The client stub object likewise owns no subsystem state. Its table pointer is shared by calls using that linked object,
so a successful require in one interpreter does not establish initialization in another. Always check the returned
version pointer for each initialization attempt. A previous dispatch table remains selected on failure, including the
case where a package exists but publishes no client data. Native package teardown does not free this borrowed pointer
through FreeInitData.