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

FreeBSD Manual Pages

  
 
  

home | help
NRE(3)			    Tcl	Library	Procedures			NRE(3)

______________________________________________________________________________

NAME
       Tcl_NRCreateCommand,  Tcl_NRCallObjProc,	Tcl_NREvalObj, Tcl_NREvalObjv,
       Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stack-
       less) evaluation	of Tcl scripts.

SYNOPSIS
       #include	<tcl.h>

       Tcl_Command
       Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
			   deleteProc)

       int
       Tcl_NRCallObjProc(interp, nreProc, clientData, objc, objv)

       int
       Tcl_NREvalObj(interp, objPtr, flags)

       int
       Tcl_NREvalObjv(interp, objc, objv, flags)

       int
       Tcl_NRCmdSwap(interp, cmd, objc,	objv, flags)

       int
       Tcl_NRExprObj(interp, objPtr, resultPtr)

       void
       Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)

ARGUMENTS
       Tcl_Interp *interp (in)		       The relevant Interpreter.

       char *cmdName (in)		       Name of the command to create.

       Tcl_ObjCmdProc *proc (in)	       Called  in  order to evaluate a
					       command.	 Is often just a small
					       wrapper that uses Tcl_NRCallOb-
					       jProc to	call nreProc  using  a
					       new trampoline.	Behaves	in the
					       same way	as the	proc  argument
					       to      Tcl_CreateObjCommand(3)
					       (q.v.).

       Tcl_ObjCmdProc *nreProc (in)	       Called instead of proc  when  a
					       trampoline is already in	use.

       ClientData clientData (in)	       Arbitrary one-word value	passed
					       to  proc,  nreProc,  deleteProc
					       and objProc.

       Tcl_CmdDeleteProc *deleteProc (in/out)  Called	 before	  cmdName   is
					       deleted from  the  interpreter,
					       allowing	 for  command-specific
					       cleanup.	May be NULL.

       int objc	(in)			       Number of items in objv.

       Tcl_Obj **objv (in)		       Words in	the command.

       Tcl_Obj *objPtr (in)		       A script	or expression to eval-
					       uate.

       int flags (in)			       As described for	Tcl_EvalObjv.

       Tcl_Command cmd (in)		       Token to	use instead of one de-
					       rived from the  first  word  of
					       objv  in	 order	to  evaluate a
					       command.

       Tcl_Obj *resultPtr (out)		       Pointer to an unshared  Tcl_Obj
					       where the result	of the evalua-
					       tion is stored  if  the	return
					       code is TCL_OK.

       Tcl_NRPostProc *postProcPtr (in)	       A function to push.

       ClientData data0	(in)

       ClientData data1	(in)

       ClientData data2	(in)

       ClientData data3	(in)		       data0  through  data3  are four
					       one-word	values	that  will  be
					       passed  to  the function	desig-
					       nated by	postProcPtr when it is
					       invoked.
______________________________________________________________________________

DESCRIPTION
       These  functions	provide	an interface to	the function stack that	an in-
       terpreter iterates through to evaluate commands.	 The routine behind  a
       command	is implemented by an initial function and any additional func-
       tions that the routine pushes onto the stack as it progresses.  The in-
       terpreter itself	pushes functions onto the stack	to react to the	end of
       a routine and to	exercise other forms of	control	such as	switching  be-
       tween  in-progress  stacks and the evaluation of	other scripts at addi-
       tional levels without adding frames to the C stack.  To execute a  rou-
       tine,  the  initial function for	the routine is called and then a small
       bit of code called a trampoline iteratively  takes  functions  off  the
       stack  and calls	them, using the	value of the last call as the value of
       the routine.

       Tcl_NRCallObjProc calls nreProc using a new trampoline.

       Tcl_NRCreateCommand, an alternative to  Tcl_CreateObjCommand,  resolves
       cmdName,	 which	may contain namespace qualifiers, relative to the cur-
       rent namespace, creates a command by that name, and returns a token for
       the  command  which  may	be used	in subsequent calls to Tcl_GetCommand-
       Name.  Except for a few cases noted below any existing command  by  the
       same  name  is  first  deleted.	 If  interp is in the process of being
       deleted Tcl_NRCreateCommand does	 not  create  any  command,  does  not
       delete any command, and returns NULL.

       Tcl_NREvalObj pushes a function that is like Tcl_EvalObjEx but consumes
       no space	on the C stack.

       Tcl_NREvalObjv pushes a function	that is	like Tcl_EvalObjv but consumes
       no space	on the C stack.

       Tcl_NRCmdSwap  is like Tcl_NREvalObjv, but uses cmd, a token previously
       returned	by Tcl_CreateObjCommand	or Tcl_GetCommandFromObj,  instead  of
       resolving the first word	of objv.

       Tcl_NRExprObj  pushes a function	that evaluates objPtr as an expression
       in the same manner as Tcl_ExprObj but without consuming space on	the  C
       stack.

       All  of	the  functions	return TCL_OK if the evaluation	of the script,
       command,	or expression has been scheduled successfully.	Otherwise (for
       example	if the command name cannot be resolved), they return TCL_ERROR
       and store a message as the interpreter's	result.

       Tcl_NRAddCallback pushes	postProcPtr.  The signature for	Tcl_NRPostProc
       is:

	      typedef int
	      Tcl_NRPostProc(
		      ClientData data[],
		      Tcl_Interp *interp,
		      int result);

       data  is	 a pointer to an array containing data0	through	data3.	result
       is the value returned by	the previous function  implementing  part  the
       routine.

EXAMPLE
       The following command uses Tcl_EvalObjEx, which consumes	space on the C
       stack, to evalute a script:

	      int
	      TheCmdOldObjProc(
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  int result;
		  Tcl_Obj *objPtr;

		  ... preparation ...

		  result = Tcl_EvalObjEx(interp, objPtr, 0);

		  ... postprocessing ...

		  return result;
	      }
	      Tcl_CreateObjCommand(interp, "theCommand",
		      TheCmdOldObjProc,	clientData, TheCmdDeleteProc);

       To avoid	consuming space	on the C stack,	TheCmdOldObjProc is renamed to
       TheCmdNRObjProc	and  the  postprocessing step is split into a separate
       function, TheCmdPostProc, which is  pushed  onto	 the  function	stack.
       Tcl_EvalObjEx  is  replaced with	Tcl_NREvalObj, which uses a trampoline
       instead of consuming space on the C stack.  A  new  version  of	TheCm-
       dOldObjProc  is	just  a	 a wrapper that	uses Tcl_NRCallObjProc to call
       TheCmdNRObjProc:

	      int
	      TheCmdOldObjProc(
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
			  clientData, objc, objv);
	      }

	      int
	      TheCmdNRObjProc
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  Tcl_Obj *objPtr;

		  ... preparation ...

		  Tcl_NRAddCallback(interp, TheCmdPostProc,
			  data0, data1,	data2, data3);
		  /* data0 .. data3 are	up to four one-word items to
		   * pass to the postprocessing	procedure */

		  return Tcl_NREvalObj(interp, objPtr, 0);
	      }

	      int
	      TheCmdNRPostProc(
		  ClientData data[],
		  Tcl_Interp *interp,
		  int result)
	      {
		  /* data[0] ..	data[3]	are the	four words of data
		   * passed to Tcl_NRAddCallback */

		  ... postprocessing ...

		  return result;
	      }

       Any function comprising a routine can push other	functions,  making  it
       possible	implement looping and sequencing constructs using the function
       stack.

SEE ALSO
       Tcl_CreateCommand(3),	Tcl_CreateObjCommand(3),     Tcl_EvalObjEx(3),
       Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)

KEYWORDS
       stackless,  nonrecursive,  execute,  command,  global,  value,  result,
       script

COPYRIGHT
       Copyright (c) 2008 by Kevin B. Kenny.  Copyright	 (c)  2018  by	Nathan
       Coulter.

Tcl				      8.6				NRE(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | EXAMPLE | SEE ALSO | KEYWORDS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_NRAddCallback.tcl86&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help