Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
critcl::iassoc(n)	   C Runtime In	Tcl (CriTcl)	     critcl::iassoc(n)

______________________________________________________________________________

NAME
       critcl::iassoc -	CriTcl Utilities: Tcl Interp Associations

SYNOPSIS
       package require Tcl  8.4

       package require critcl  ?3.1?

       package require critcl::iassoc  ?1.1?

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

______________________________________________________________________________

DESCRIPTION
       C Runtime In Tcl, or CriTcl , is	a system for compiling C code embedded
       in Tcl on the fly and either loading the	resulting objects into Tcl for
       immediate  use  or  packaging them for distribution.  Use CriTcl	to im-
       prove performance by rewriting in C those routines that are performance
       bottlenecks.

       This  document is the reference manpage for the critcl::iassoc package.
       This package provides convenience commands for  advanced	 functionality
       built on	top of the critcl core.

       With  it	 a  user wishing to associate some data	with a Tcl interpreter
       via Tcl's Tcl_(Get|Set)AssocData() APIs can now concentrate on the data
       itself,	while  all  the	 necessary boilerplate around it is managed by
       this package.

       Its intended audience are mainly	developers wishing to write Tcl	 pack-
       ages with embedded C code.

       This package resides in the Core	Package	Layer of CriTcl.

       +----------------+
       |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 which pro-
	      vides access to a	structure associated with a Tcl	interpreter.

	      The C code code fragment struct defines  the  elements  of  said
	      structure,  whereas the fragments	constructor and	destructor are
	      C	code blocks executed to	initialize and release any dynamically
	      allocated	 parts	of  this structure, when needed. Note that the
	      structure	itself is managed by the system.

	      The new function takes a Tcl_Interp* pointer refering to the in-
	      terpreter	 whose	structure we wish to obtain as the first argu-
	      ment, 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 identi-
	      fiers 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 fail-
	      ure.

	      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 ini-
			    tialize.

		     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.

		     ...    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  be-
			    longed to.

EXAMPLE
       The  example  shown below is the	specification of a simple interpreter-
       associated counter. The full example, with meta data and	other inciden-
       tals,  can  be  found  in  the directory	"examples/queue" of the	critcl
       source distribution/repository.

	      package require Tcl 8.4
	      package require critcl 3.1

	      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
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and other problems.  Please report	such at	https://github.com/an-
       dreas-kupries/critcl.  Please also report any  ideas  for  enhancements
       you may have for	either package and/or documentation.

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

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				      1.1		     critcl::iassoc(n)

NAME | SYNOPSIS | DESCRIPTION | API | EXAMPLE | AUTHORS | BUGS, IDEAS, FEEDBACK | KEYWORDS | CATEGORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=critcl_iassoc&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help