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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       critcl::bitmap -	CriTcl Utilities: Bitset en- and decoding

SYNOPSIS
       package require Tcl  8.4

       package require critcl  ?3.1.11?

       package require critcl::bitmap  ?1.0.1?

       ::critcl::bitmap::def name definition ?exclusions?

______________________________________________________________________________

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::bitmap package.
       This package provides convenience commands for  advanced	 functionality
       built on	top of both critcl core	and package critcl::iassoc.

       C level libraries often use bit-sets to encode many flags into a	single
       value. Tcl bindings to such libraries now have the task of converting a
       Tcl  representation  of	such  flags (like a list of strings) into such
       bit-sets, and back.  Note here that the C-level information has	to  be
       something  which	already	exists.	The package does not create these val-
       ues. This is in contrast	to the package critcl::enum which  creates  an
       enumeration based on the	specified symbolic names.

       This package was	written	to make	the declaration	and management of such
       bit-sets	and their associated conversions functions  easy,  hiding  all
       attendant complexity from the user.

       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::bitmap::def name definition ?exclusions?
	      This command defines two C functions for the conversion  of  the
	      named  bit-set  into  Tcl	lists, and vice	versa.	The underlying
	      mapping tables are automatically initialized  on	first  access,
	      and finalized on interpreter destruction.

	      The  definition  dictionary  provides  the mapping from the Tcl-
	      level symbolic names of the flags	to their C expressions	(often
	      the  name	 of the	macro specifying the actual value).  Note here
	      that the C-level information has to be something	which  already
	      exists.  The  package  does  not create these values. This is in
	      contrast to the package critcl::enum which creates  an  enumera-
	      tion based on the	specified symbolic names.

	      The  optional  exlusion list is for the flags/bit-sets for which
	      conversion from bit-set to flag, i.e. decoding makes  no	sense.
	      One  case	for such, for example, are flags representing a	combi-
	      nation of	other flags.

	      The package generates multiple things (declarations and  defini-
	      tions)  with names derived from name, which has to be a proper C
	      identifier.

	      name_encode
		     The function for encoding a Tcl list of strings into  the
		     equivalent	bit-set.  Its signature	is

		     int name_encode (Tcl_Interp* interp, Tcl_Obj* flags, int* result);

	      The  return  value  of  the  function  is	a Tcl error code, i.e.
	      TCL_OK, TCL_ERROR, etc.

	      name_decode
		     The function for decoding a bit-set into  the  equivalent
		     Tcl list of strings.  Its signature is

		     Tcl_Obj* name_decode (Tcl_Interp* interp, int flags);

	      name.h A	header	file  containing  the declarations for the two
		     conversion	functions, for use by other parts of the  sys-
		     tem, if necessary.

		     The generated file	is stored in a place where it will not
		     interfere with the	overall	system outside of the package,
		     yet also be available for easy inclusion by package files
		     (csources).

	      name   The name of a critcl argument type	encapsulating the  en-
		     coder function for	use by critcl::cproc.

	      name   The  name	of  a critcl result type encapsulating the de-
		     coder function for	use by critcl::cproc.

EXAMPLE
       The example shown below is the specification of the event flags	pulled
       from the	draft work on a	Tcl binding to Linux's inotify APIs.

	      package require Tcl 8.5
	      package require critcl 3.1.11

	      critcl::buildrequirement {
		  package require critcl::bitmap
	      }

	      critcl::bitmap::def tcl_inotify_events {
		  accessed	 IN_ACCESS
		  all		 IN_ALL_EVENTS
		  attribute	 IN_ATTRIB
		  closed	 IN_CLOSE
		  closed-nowrite IN_CLOSE_NOWRITE
		  closed-write	 IN_CLOSE_WRITE
		  created	 IN_CREATE
		  deleted	 IN_DELETE
		  deleted-self	 IN_DELETE_SELF
		  dir-only	 IN_ONLYDIR
		  dont-follow	 IN_DONT_FOLLOW
		  modified	 IN_MODIFY
		  move		 IN_MOVE
		  moved-from	 IN_MOVED_FROM
		  moved-self	 IN_MOVE_SELF
		  moved-to	 IN_MOVED_TO
		  oneshot	 IN_ONESHOT
		  open		 IN_OPEN
		  overflow	 IN_Q_OVERFLOW
		  unmount	 IN_UNMOUNT
	      }	{
		  all closed move oneshot
	      }

	      #	Declarations:	       tcl_inotify_events.h
	      #	Encoder:      int      tcl_inotify_events_encode (Tcl_Interp* interp, Tcl_Obj* flags, int* result);
	      #	Decoder:      Tcl_Obj* tcl_inotify_events_decode (Tcl_Interp* interp, int flags);
	      #	crit arg-type	       tcl_inotify_events
	      #	crit res-type	       tcl_inotify_events

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

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				     1.0.1		     critcl::bitmap(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_bitmap&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help