Tcl_Preserve man page on Mageia

Printed from http://www.polarhome.com/service/man/?qf=Tcl_Preserve&af=0&tf=2&of=Mageia

Tcl_Preserve(3)		    Tcl Library Procedures	       Tcl_Preserve(3)

______________________________________________________________________________

NAME
       Tcl_Preserve,  Tcl_Release,  Tcl_EventuallyFree - avoid freeing storage
       while it is being used

SYNOPSIS
       #include <tcl.h>

       Tcl_Preserve(clientData)

       Tcl_Release(clientData)

       Tcl_EventuallyFree(clientData, freeProc)

ARGUMENTS
       ClientData clientData (in)	     Token describing structure to  be
					     freed  or reallocated.  Usually a
					     pointer to memory for structure.

       Tcl_FreeProc *freeProc (in)	     Procedure	to  invoke   to	  free
					     clientData.
_________________________________________________________________

DESCRIPTION
       These  three  procedures help implement a simple reference count mecha‐
       nism for managing storage.  They are designed to solve a problem having
       to  do  with  widget deletion, but are also useful in many other situa‐
       tions.  When a widget is deleted,  its  widget  record  (the  structure
       holding	information  specific  to  the widget) must be returned to the
       storage allocator.  However, it is possible that the widget  record  is
       in  active use by one of the procedures on the stack at the time of the
       deletion.  This can happen, for example, if the command associated with
       a  button  widget causes the button to be destroyed:  an X event causes
       an event-handling C procedure in the button to  be  invoked,  which  in
       turn  causes  the button's associated Tcl command to be executed, which
       in turn causes the button to be deleted, which in turn causes the  but‐
       ton's  widget  record  to be de-allocated.  Unfortunately, when the Tcl
       command returns, the button's event-handling  procedure	will  need  to
       reference  the  button's	 widget	 record.   Because of this, the widget
       record must not be freed as part of the deletion, but must be  retained
       until the event-handling procedure has finished with it.	 In other sit‐
       uations where the widget is deleted, it may be  possible	 to  free  the
       widget record immediately.

       Tcl_Preserve  and Tcl_Release implement short-term reference counts for
       their clientData	 argument.   The  clientData  argument	identifies  an
       object  and usually consists of the address of a structure.  The refer‐
       ence counts guarantee that an object will not be freed until each  call
       to   Tcl_Preserve   for	the  object  has  been	matched	 by  calls  to
       Tcl_Release.  There may be any number of unmatched  Tcl_Preserve	 calls
       in effect at once.

       Tcl_EventuallyFree  is  invoked to free up its clientData argument.  It
       checks to see if there are unmatched Tcl_Preserve calls for the object.
       If  not, then Tcl_EventuallyFree calls freeProc immediately.  Otherwise
       Tcl_EventuallyFree records the fact that clientData needs eventually to
       be  freed.  When all calls to Tcl_Preserve have been matched with calls
       to Tcl_Release then freeProc will be called by Tcl_Release  to  do  the
       cleanup.

       All  the work of freeing the object is carried out by freeProc.	FreeP‐
       roc must have arguments and result that match the type Tcl_FreeProc:
	      typedef void Tcl_FreeProc(char *blockPtr);
       The blockPtr argument to freeProc will be the same  as  the  clientData
       argument	 to Tcl_EventuallyFree.	 The type of blockPtr (char *) is dif‐
       ferent than the type of the clientData argument	to  Tcl_EventuallyFree
       for historical reasons, but the value is the same.

       When  the  clientData  argument to Tcl_EventuallyFree refers to storage
       allocated and returned by  a  prior  call  to  Tcl_Alloc,  ckalloc,  or
       another	function of the Tcl library, then the freeProc argument should
       be given the special value of TCL_DYNAMIC.

       This mechanism can be used to solve  the	 problem  described  above  by
       placing	Tcl_Preserve  and  Tcl_Release	calls  around actions that may
       cause undesired storage re-allocation.  The mechanism is intended  only
       for  short-term	use  (i.e. while procedures are pending on the stack);
       it will not work efficiently as a  mechanism  for  long-term  reference
       counts.	 The implementation does not depend in any way on the internal
       structure of the objects being freed;  it keeps the reference counts in
       a separate structure.

SEE ALSO
       Tcl_Interp, Tcl_Alloc

KEYWORDS
       free, reference count, storage

Tcl				      7.5		       Tcl_Preserve(3)
[top]

List of man pages available for Mageia

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net