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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       critcl::callback	- CriTcl C-level Callback Utilities

SYNOPSIS
       package require Tcl  8.4

       package require critcl  ?3.1?

       package require critcl::callback	 ?0.1?

       critcl_callback_p critcl_callback_new interp objc objv nargs

       void critcl_callback_extend callback argument

       void critcl_callback_destroy callback

       int critcl_callback_invoke callback objc	objv

______________________________________________________________________________

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::callback pack-
       age.  This package provides, via	a stubs	API table, data	structures and
       functions  to  manage  callbacks	from C to Tcl. The package has no Tcl-
       level facilities.  Its intended audience	are mainly developers  wishing
       to  write  Tcl  packages	 with embedded C code who have to invoke user-
       specified command (prefixes) in Tcl.

       This package resides in the Support Package Layer of CriTcl.

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

       +----------------+
       |Core Packages	|
       | critcl		|
       | critcl::util	|
       +----------------+

       *================*
       |Support	Packages|
       | stubs::*	|
       | md5, platform	|
       |  ...		|
       *================*

API
       The package API consist of  one	opaque	data  structure	 (critcl_call-
       back_p) and four	functions operating on the same.  These	functions are

       critcl_callback_p critcl_callback_new interp objc objv nargs
	      This function creates a new callback (manager) and returns it as
	      its result.

	      The callback is initialized with the Tcl_Interp* interp specify-
	      ing  where to run	the callback, the fixed	part of	the command to
	      run in standard objc/objv	notation, plus the number of free  ar-
	      guments to expect	after the fixed	part.

	      The  fixed  part	is  the	 essentially the command prefix	of the
	      callback.

	      All Tcl_Obj* elements of objv are	protected  against  early  re-
	      lease  by	 incrementing their reference counts. The callback ef-
	      fectively	takes ownership	of these objects.

       void critcl_callback_extend callback argument
	      This function takes a callback of	type critcl_callback_p and ex-
	      tends  its  fixed	 part with the argument, taking	the first free
	      slot for arguments to do so.  This means that after the applica-
	      tion  of this function the specified callback has	one free argu-
	      ment less.

	      With assertions active attempting	to extend beyond the number of
	      free arguments will cause	a panic. Without assertions active ex-
	      pect a crash at some point.

	      This allows the user to extend the fixed part  of	 the  callback
	      with  semi-fixed elements, like method names (See	Multiple meth-
	      ods).

	      The argument is protected	against	early release by  incrementing
	      its reference count. The callback	effectively takes ownership of
	      this object.

       void critcl_callback_destroy callback
	      This function takes a callback of	type critcl_callback_p and re-
	      leases all memory	associated with	it.  After application of this
	      function the callback cannot be used anymore.

	      All fixed	elements of the	callback (owned	by it) are released by
	      decrementing their reference counts.

       int critcl_callback_invoke callback objc	objv
	      This function invokes the	callback in the	Tcl interpreter	speci-
	      fied at the time of construction,	in the global level and	 name-
	      space,  with  the	 free arguments	filled by the Tcl_Obj* objects
	      specified	via objc/objv.

	      It returns the Tcl status	of the invoked command as its  result.
	      Any  further  results or error messages will be found in the re-
	      sult area	of the Tcl interpreter in question. The	 exact	nature
	      of such is dependent on the callback itself.

	      With  assertions	active	attempting  to use more	arguments than
	      available	will cause a panic. Without assertions active expect a
	      crash at some point.

	      While  the callback is running all Tcl_Obj* elements of the com-
	      mand, fixed and arguments, are protected against	early  release
	      by temporarily incrementing their	reference counts.

EXAMPLES
   SIMPLE CALLBACK
       The  example  here  shows the important parts of	using the functions of
       this package for	a simple callback which	is invoked with	a single argu-
       ment, some kind of data to hand to the Tcl level.

		  // Create the	callback with interpreter and command prefix in
		  // oc/ov, plus space for the argument
		  critcl_callback_p cb = critcl_callback_new (interp, oc, ov, 1);

		  // Invoke the	callback somewhere in the C package using this one,
		  // with Tcl_Obj* data	holding	the information	to pass	up.
		  critcl_callback_invoke (cb, 1, &data);

		  // At	the end	of the lifetime, release the callback.
		  critcl_callback_destroy (cb);

       Note that the functions of this package are designed for	the case where
       the created callback (cb	above) is kept around for  a  long  time,  and
       many different invokations.

       Using  the  sequence  above as is, creating and destroying the callback
       each time it is invoked will yield very poor performance	 and  lots  of
       undesirable memory churn.

   MULTIPLE METHODS
       While  we can use the methodology of the	previous section when a	single
       (Tcl-level) callback is invoked from different places in	C,  with  dif-
       ferent  methods,	 simply	having another argument	slot and filling it an
       invokation time with the	method object, a second	methodology is open to
       us due to critcl_callback_extend.

		  // Create one	callback manager per different method the callback
		  // will be used with.	Fill the first of the two declared arguments
		  // with the different	methods.
		  critcl_callback_p cb_a = critcl_callback_new (interp,	oc, ov,	2);
		  critcl_callback_p cb_b = critcl_callback_new (interp,	oc, ov,	2);

		  critcl_callback_extend (cb_a,	Tcl_NewStringObj ("method1", -1));
		  critcl_callback_extend (cb_b,	Tcl_NewStringObj ("method2", -1));

		  // After the extension we have one free argument left, for use in
		  // the invokations.

		  critcl_callback_invoke (cb_a,	1, &dataX);

		  critcl_callback_invoke (cb_b,	1, &dataY);

		  // At	the end	release	both managers again
		  critcl_callback_destroy (cb_a);
		  critcl_callback_destroy (cb_b);

       The  nice thing here is that the	method objects are allocated only once
       and automatically shared	by all the calls. No memory churn  to  repeat-
       edly allocate the same string objects over and over again.

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,	code generator,	compile	& run,	compiler,  dy-
       namic  code  generation,	dynamic	compilation, generate package, linker,
       on demand compilation, on-the-fly compilation

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				      0.1		   critcl::callback(n)

NAME | SYNOPSIS | DESCRIPTION | API | EXAMPLES | 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_callback&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help