DOKK / manpages / debian 11 / critcl / critcl_cutil.3tcl.en
critcl::cutil(3tcl) C Runtime In Tcl (CriTcl) critcl::cutil(3tcl) 







critcl::cutil - CriTcl C-level Utilities








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);












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 improve 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 writing of memory allocations, assertions, and narrative
    tracing and provides 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.









  
::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 becomes 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 becomes
        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 assertions 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 becomes 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 companion 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 tracing facility in general.


The details of the semantics are explained in section
    Tracing


The result of the command is an empty string.









  

  
This macro allocates a single element of the given type and returns
      a pointer to that memory.

  

  
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 management
        information in the structure itself, and the value/payload immediately
        after, in the same memory block.

  

  

  
This macro allocates n elements of the given type and
      returns a pointer to that memory.

  

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

  

  
This macro releases the memory referenced by the pointer variable
      var.

  

  
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.

  

  
This macro properly sets the string representation of the Tcl object
      o to a copy of the string held by the DString
    ds.

  

  
This macro duplicates the string str into the heap and stores the
      result into the named char* variable var.











  

  
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.

  

  
This macro ensures that the index is in the range 0 to
      size-1.

  

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










All output is printed to stdout.



  

  

  

  

  

  

  

  
These "commands" are actually declarators, for use outside of
      functions. They (de)activate specific logical streams, named either
      explicitly by the user, or implicitly, refering to the current file.
    
For example:

    

  








    TRACE_TAG_ON (lexer_in);





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



  

  

  

  

  

  

  

  
Use these macros at the beginning of a C function to record entry into it.
      The name of the entered function is an implicit argument
      (__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.

  

  

  

  

  
Use these macros instead of






return





  

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





  

  

  

  
Use this macro instead of






return x





  

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





  

  

  

  
This macro is the trace facilities' equivalent of printf, printing
      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.

  

  

  

  

  
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.

  

  

  

  
This is the low-level macro which prints the end of a trace line.

  

  

  

  
This is the low-level macro which adds formatted data to the line.

  

  

  

  

  

  
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.

  

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

  

  
Conditionally insert the code at compile time when the tracing
      facility is activated.

  

  

  

  
Insert the code at compile time when the tracing facility is
      activated, and execute the same when either the implicit tag for the file
      or the user-specified tag is active.










Andreas Kupries








This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such at
    https://github.com/andreas-kupries/critcl. Please also report any
    ideas for enhancements you may have for either package and/or
  documentation.








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








Glueing/Embedded C code








Copyright (c) 2011-2018 Andreas Kupries








  

    0.2
    doc