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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       critcl::cutil - CriTcl C-level Utilities

SYNOPSIS
       package require Tcl  8.4

       package require critcl  ?2.1?

       package require critcl::cutil  ?0.2?

       ::critcl::cutil::alloc

       ::critcl::cutil::assertions ?enable?

       ::critcl::cutil::tracer ?enable?

       type* ALLOC (type)

       type* ALLOC_PLUS	(type, int n)

       type* NALLOC (type, int n)

       type* REALLOC (type* var, type, int n)

       void FREE (type*	var)

       void STREP (Tcl_Obj* o, char* s,	int len)

       void STREP_DS (Tcl_Obj* o, Tcl_DString* ds)

       void STRDUP (varname, char* str)

       void ASSERT (expression,	char* message

       void ASSERT_BOUNDS (int index, int size)

       void STOPAFTER(n)

       TRACE_ON

       TRACE_OFF

       TRACE_TAG_ON  (identifier)

       TRACE_TAG_OFF (identifier)

       void TRACE_FUNC

       void TRACE_TAG_FUNC (tag)

       void TRACE_FUNC_VOID

       void TRACE_TAG_FUNC_VOID	(tag)

       void TRACE_RETURN_VOID

       void TRACE_TAG_RETURN_VOID (tag)

       any TRACE_RETURN	    (	  char*	format,	any x)

       any TRACE_TAG_RETURN (tag, char*	format,	any x)

       void TRACE     (	    char* format, ...)

       void TRACE_TAG (tag, char* format, ...)

       void TRACE_HEADER (int indent)

       void TRACE_TAG_HEADER (tag, int indent)

       void TRACE_CLOSER

       void TRACE_TAG_CLOSER (tag)

       void TRACE_ADD	       (const char* format, ...)

       void TRACE_TAG_ADD (tag,	const char* format, ...)

       void TRACE_PUSH_SCOPE (const char* name)

       void TRACE_PUSH_FUNC

       void TRACE_PUSH_POP

       TRACE_TAG_VAR (tag)

       TRACE_RUN (code);

       TRACE_DO	(code);

       TRACE_TAG_DO (tag, code);

______________________________________________________________________________

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::cutil package.
       This package encapsulates a number of C-level utilites for easier writ-
       ing  of	memory allocations, assertions,	and narrative tracing and pro-
       vides convenience commands to make these	utilities accessible to	critcl
       projects.  Its intended audience	are mainly developers wishing to write
       Tcl packages 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	|
       |  ...		|
       +----------------+

       The reason for this is that the main critcl package makes  use  of  the
       facilities  for	narrative tracing when critcl::config trace is set, to
       instrument commands and procedures.

API
       ::critcl::cutil::alloc
	      This command provides a number C-preprocessor macros which  make
	      the  writing  of memory allocations for structures and arrays of
	      structures easier.

	      When run the  header  file  "critcl_alloc.h"  is	directly  made
	      available	 to the	".critcl" file containing the command, and be-
	      comes available for use in #include directives  of  companion  C
	      code declared via	critcl::csources.

	      The macros definitions and their signatures are:

		  type*	ALLOC (type)
		  type*	ALLOC_PLUS (type, int n)
		  type*	NALLOC (type, int n)
		  type*	REALLOC	(type* var, type, int n)
		  void	FREE (type* var)

		  void STREP	(Tcl_Obj* o, char* s, int len);
		  void STREP_DS	(Tcl_Obj* o, Tcl_DString* ds);
		  void STRDUP	(varname, char*	str);

       The details of the semantics are	explained in section Allocation.

       The result of the command is an empty string.

       ::critcl::cutil::assertions ?enable?
	      This  command  provides  a  number C-preprocessor	macros for the
	      writing of assertions in C code.

	      When invoked the header file "critcl_assert.h" is	directly  made
	      available	 to the	".critcl" file containing the command, and be-
	      comes available for use in #include directives  of  companion  C
	      code declared via	critcl::csources.

	      The macro	definitions and	their signatures are

		  void ASSERT (expression, char* message);
		  void ASSERT_BOUNDS (int index, int size);

		  void STOPAFTER (int n);

       Note  that  these  definitions  are conditional on the existence	of the
       macro CRITCL_ASSERT.  Without a critcl::cflags -DCRITCL_ASSERT all  as-
       sertions	 in  the C code	are quiescent and not compiled into the	object
       file. In	other words, assertions	can be (de)activated  at  will	during
       build time, as needed by	the user.

       For  convenience	 this  is controlled by	enable.	By default (false) the
       facility	available, but not active.   Using  true  not  only  makes  it
       available, but activates	it as well.

       The details of the semantics are	explained in section Assertions.

       The result of the command is an empty string.

       ::critcl::cutil::tracer ?enable?
	      This command provides a number C-preprocessor macros for tracing
	      C-level internals.

	      When invoked the header file "critcl_trace.h" is	directly  made
	      available	 to the	".critcl" file containing the command, and be-
	      comes available for use in #include directives  of  companion  C
	      code  declared  via  critcl::csources. Furthermore the ".c" file
	      containing the runtime support is	added to the set of C  compan-
	      ion files

	      The macro	definitions and	their signatures are

		  /* (de)activation of named logical streams.
		   * These are declarators, not	statements.
		   */

		  TRACE_ON;
		  TRACE_OFF;
		  TRACE_TAG_ON	(tag_identifier);
		  TRACE_TAG_OFF	(tag_identifier);

		  /*
		   * Higher level trace	statements (convenience	commands)
		   */

		  void TRACE_FUNC   (const char* format, ...);
		  void TRACE_FUNC_VOID;
		  any  TRACE_RETURN (const char* format, any x);
		  void TRACE_RETURN_VOID;
		  void TRACE (const char* format, ...);

		  /*
		   * Low-level trace statements	the higher level ones above
		   * are composed from.	Scope management and output management.
		   */

		  void TRACE_PUSH_SCOPE	(const char* scope);
		  void TRACE_PUSH_FUNC;
		  void TRACE_POP;

		  void TRACE_HEADER (int indent);
		  void TRACE_ADD (const	char* format, ...);
		  void TRACE_CLOSER;

		  /*
		   * Convert tag to the	underlying status variable.
		   */

		  TRACE_TAG_VAR	(tag)

		  /*
		   * Conditional use of	arbitrary code.
		   */

		  TRACE_RUN (code);
		  TRACE_DO (code);
		  TRACE_TAG_DO (code);

       Note  that  these  definitions  are conditional on the existence	of the
       macro CRITCL_TRACER.   Without  a  critcl::cflags  -DCRITCL_TRACER  all
       trace  functionality  in	 the C code is quiescent and not compiled into
       the object file.	In other words,	tracing	can be (de)activated  at  will
       during build time, as needed by the user.

       For  convenience	 this  is controlled by	enable.	By default (false) the
       facility	available, but not active.   Using  true  not  only  makes  it
       available,  but	activates  it  as well.	 Further note that the command
       critcl::config now accepts a boolean option trace. Setting it activates
       enter/exit  tracing in all commands based on critcl::cproc, with	proper
       printing	of arguments and results. This implicitly activates the	 trac-
       ing facility in general.

       The details of the semantics are	explained in section Tracing

       The result of the command is an empty string.

ALLOCATION
       type* ALLOC (type)
	      This  macro allocates a single element of	the given type and re-
	      turns a pointer to that memory.

       type* ALLOC_PLUS	(type, int n)
	      This macro allocates a single element of the given type, plus an
	      additional  n bytes after	the structure and returns a pointer to
	      that memory.

	      This is for variable-sized structures of.	 An  example  of  such
	      could  be	 a generic list	element	structure which	stores manage-
	      ment information in the structure	itself,	and the	 value/payload
	      immediately after, in the	same memory block.

       type* NALLOC (type, int n)
	      This  macro allocates n elements of the given type and returns a
	      pointer to that memory.

       type* REALLOC (type* var, type, int n)
	      This macro expands or shrinks the	memory associated with	the  C
	      variable var of type type	to hold	n elements of the type.	It re-
	      turns a pointer to that memory.  Remember,  a  reallocation  may
	      move  the	 data  to  a new location in memory to satisfy the re-
	      quest. Returning a pointer instead of immediately	 assigning  it
	      to  the  var  allows the user to validate	the new	pointer	before
	      trying to	use it.

       void FREE (type*	var)
	      This macro releases the memory referenced	by the	pointer	 vari-
	      able var.

       void STREP (Tcl_Obj* o, char* s,	int len)
	      This  macro  properly  sets the string representation of the Tcl
	      object o to a copy of the	string s, expected  to	be  of	length
	      len.

       void STREP_DS (Tcl_Obj* o, Tcl_DString* ds)
	      This  macro  properly  sets the string representation of the Tcl
	      object o to a copy of the	string held by the DString ds.

       void STRDUP (varname, char* str)
	      This macro duplicates the	string str into	the  heap  and	stores
	      the result into the named	char* variable var.

ASSERTIONS
       void ASSERT (expression,	char* message
	      This  macro tests	the expression and panics if it	does not hold.
	      The specified message is used as part of the panic.  The message
	      has to be	a static string, it cannot be a	variable.

       void ASSERT_BOUNDS (int index, int size)
	      This macro ensures that the index	is in the range	0 to size-1.

       void STOPAFTER(n)
	      This  macro  throws  a  panic after it is	called n times.	 Note,
	      each separate instance of	the macro has its own counter.

TRACING
       All output is printed to	stdout.

       TRACE_ON

       TRACE_OFF

       TRACE_TAG_ON  (identifier)

       TRACE_TAG_OFF (identifier)
	      These "commands" are actually declarators, for  use  outside  of
	      functions. They (de)activate specific logical streams, named ei-
	      ther explicitly by the user, or implicitly, refering to the cur-
	      rent file.

	      For example:

		  TRACE_TAG_ON (lexer_in);

       All  high-  and low-level trace commands	producing output have the con-
       trolling	tag as an implicit argument. The scope management commands  do
       not take	tags.

       void TRACE_FUNC

       void TRACE_TAG_FUNC (tag)

       void TRACE_FUNC_VOID

       void TRACE_TAG_FUNC_VOID	(tag)
	      Use  these macros	at the beginning of a C	function to record en-
	      try into it. The name of the entered function is an implicit ar-
	      gument (__func__), forcing users to have a C99 compiler..

	      The  tracer's  runtime maintains a stack of active functions and
	      expects that function return is signaled by either TRACE_RETURN,
	      TRACE_RETURN_VOID, or the	equivalent forms taking	a tag.

       void TRACE_RETURN_VOID

       void TRACE_TAG_RETURN_VOID (tag)
	      Use these	macros instead of

	      return

       to     function.	 Beyond	 returning from	the function this also signals
	      the same to the tracer's runtime,	popping	the last entered func-
	      tion from	its stack of active functions.

       any TRACE_RETURN	    (	  char*	format,	any x)

       any TRACE_TAG_RETURN (tag, char*	format,	any x)
	      Use this macro instead of

	      return x

       to     non-void	function.   Beyond  returning  from  the function with
	      value x this also	signals	the same to the	tracer's runtime, pop-
	      ping  the	 last  entered function	from its stack of active func-
	      tions.  The format is expected to	be a proper formatting	string
	      for printf and analogues,	able to	stringify x.

       void TRACE     (	    char* format, ...)

       void TRACE_TAG (tag, char* format, ...)
	      This macro is the	trace facilities' equivalent of	printf,	print-
	      ing arbitrary data under the control of the format.

	      The printed text is closed with a	newline, and indented  as  per
	      the stack	of active functions.

       void TRACE_HEADER (int indent)

       void TRACE_TAG_HEADER (tag, int indent)
	      This  is	the  low-level	macro  which prints the	beginning of a
	      trace line. This prefix consists of physical location (file name
	      and  line	number), if available, indentation as per the stack of
	      active scopes (if	activated), and	the name of the	active scope.

       void TRACE_CLOSER

       void TRACE_TAG_CLOSER (tag)
	      This is the low-level macro which	prints	the  end  of  a	 trace
	      line.

       void TRACE_ADD	       (const char* format, ...)

       void TRACE_TAG_ADD (tag,	const char* format, ...)
	      This  is	the  low-level	macro which adds formatted data	to the
	      line.

       void TRACE_PUSH_SCOPE (const char* name)

       void TRACE_PUSH_FUNC

       void TRACE_PUSH_POP
	      These are	the low-level macros for scope management.  The	 first
	      two  forms  push	a new scope on the stack of active scopes, and
	      the last forms pops the last scope pushed.

       TRACE_TAG_VAR (tag)
	      Helper macro converting from a tag identifier to the name	of the
	      underlying status	variable.

       TRACE_RUN (code);
	      Conditionally  insert  the code at compile time when the tracing
	      facility is activated.

       TRACE_DO	(code);

       TRACE_TAG_DO (tag, code);
	      Insert the code at compile time when the tracing facility	is ac-
	      tivated,	and  execute the same when either the implicit tag for
	      the file or the user-specified tag is active.

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.2		      critcl::cutil(n)

NAME | SYNOPSIS | DESCRIPTION | API | ALLOCATION | ASSERTIONS | TRACING | 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_cutil&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help