critcl::iassoc(3tcl)

💖 NAME 💖

critcl::iassoc — CriTcl, but specifically the Code Gen department, and even more specifically the Tcl Interp Associations corner of it 🦋

---

✨ SYNOPSIS ✨

package require Tcl 8.6

package require critcl ?3.2?

package require critcl::iassoc ?1.2?

::critcl::iassoc::def name arguments struct constructor destructor

---

🌸 DESCRIPTION 🌸

Hiii okay so first things first, welcome to the C Runtime In Tcl (friends call it CriTcl for short) — it's the whole system for embedding and using C code from inside your Tcl scripts, like [http://core.tcl-lang.org/tcl](http://core.tcl-lang.org/tcl) scripts, no cap.

This doc right here? It's the reference manpage for the critcl::iassoc package. And what does that package do, you ask? It gives you convenience commands for the advanced functionality that sits on top of the critcl core. Basically the fancy stuff 💅

So here's the vibe: you want to associate some data with a Tcl interpreter, using Tcl's own Tcl_(Get|Set)AssocData() APIs. Normally that means writing a ton of boilerplate and crying a little. But with this package you can now just concentrate on the data itself, because all the necessary boilerplate around it is managed by the package. Not me doing the boring parts. Periodt.

Who's this for? Its intended audience is mainly developers wishing to write Tcl packages with embedded C code. So like, devs. Hi devs. 🫶

This package resides in the Core Package Layer of CriTcl. Here's the little map, iconic as always:

+----------------+
|Applications    |
| critcl         |
| critcl::app    |
+----------------+

*================*
|Core Packages   |
| critcl         |
| critcl::util   |
*================*

+----------------+
|Support Packages|
| stubs::*       |
| md5, platform  |
|  ...           |
+----------------+

---

👑 API 👑

• ::critcl::iassoc::def name arguments struct constructor destructor — this command defines a C function with the given name, and that function is your access gate to a structure associated with a Tcl interpreter. Slay.

So, the C code fragment struct is what defines the elements of said structure. Meanwhile the fragments constructor and destructor are C code blocks that get executed to initialize and release any dynamically allocated parts of this structure, when needed. And heads up — note that the structure itself is managed by the system. You don't touch that. The system has it. 🧚

Your brand new function takes a Tcl_Interp* pointer refering to the interpreter whose structure we wish to obtain as the first argument, plus the specified arguments, and returns a pointer to the associated structure, of type "name_data" (see below 👇).

The arguments are a dictionary-like list of C types and identifiers specifying additional arguments for the accessor function, and, indirectly, the constructor C code block. This is useful for the supplication of initialization values, or the return of more complex error information in case of a construction failure. iykyk.

The C types associated with the structure are derived from name, with "name_data__" the type of the structure itself, and "name_data" representing a pointer to the structure. The C code blocks can rely on the following C environments:

🎀 constructor 🎀

• data — pointer to the structure (type: name_data) to initialize.
• interp — pointer to the Tcl interpreter (type: Tcl_Interp*) the new structure will be associated with.
• error — a C code label the constructor can jump to should it have to signal a construction failure. It is the responsibility of the constructor to release any fields already initialized before jumping to this label. Like, do not forget that. Fr fr.
• ... — the names of the constructor arguments specified with arguments.

🌈 destructor 🌈

• data — pointer to the structure being released.
• interp — pointer to the Tcl interpreter the structure belonged to.

---

💜 EXAMPLE 💜

The example shown below is the specification of a simple interpreter-associated counter. The full example, with meta data and other incidentals, can be found in the directory "examples/queue" of the critcl source distribution/repository. Go look at it, it's cute.

package require Tcl 8.6
package require critcl 3.2

critcl::buildrequirement {
    package require critcl::iassoc
}

critcl::iassoc::def icounter {} {
    int counter; /* The counter variable */
} {
    data->counter = 0;
} {
    /* Nothing to release */
}

critcl::ccode {
    ... function (...)
    {
         /* Access to the data ... */
         icounter_data D = icounter (interp /* ... any declared arguments, here, none */);
   ... D->counter ...
    }
}
# or, of course, 'cproc's, 'ccommand's etc.

package provide icounter 1

---

🦋 AUTHORS 🦋

Andreas Kupries

---

😭 BUGS, IDEAS, FEEDBACK 😭

Okay so real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. Not being dramatic, it's just how it is. Please report such at [https://github.com/andreas-kupries/critcl](https://github.com/andreas-kupries/critcl).

Also please report any ideas for enhancements you may have for either package and/or documentation. We want them. Give them to us. 💖

---

⭐ KEYWORDS ⭐

C code, Embedded C Code, Tcl Interp Association, code generator, compile & run, compiler, dynamic code generation, dynamic compilation, generate package, linker, on demand compilation, on-the-fly compilation, singleton

---

💅 CATEGORY 💅

Glueing/Embedded C code

---

🌸 COPYRIGHT 🌸

Copyright (c) 2011-2024 Andreas Kupries

---

okay bestie that's the whole page, you're officially certified in interpreter associations now, go write something iconic 😌✨

doc, version 1.2 — critcl::iassoc(3tcl) — mwah, take care of her 💖