diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/NRE.3 | 103 |
1 files changed, 57 insertions, 46 deletions
@@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: NRE.3,v 1.4 2009/08/12 16:06:38 dgp Exp $ +'\" RCS: @(#) $Id: NRE.3,v 1.5 2009/11/01 13:00:07 dkf Exp $ '\" .so man.macros .TH NRE 3 8.6 Tcl "Tcl Library Procedures" @@ -17,7 +17,8 @@ Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmd \fB#include <tcl.h>\fR .sp Tcl_Command -\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData, deleteProc\fR) +\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData, + deleteProc\fR) .sp int \fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR) @@ -38,7 +39,7 @@ void \fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR) .fi .SH ARGUMENTS -.AS Tcl_CmdDeleteProc *postProcPtr in +.AS Tcl_CmdDeleteProc *interp in .AP Tcl_Interp *interp in Interpreter in which to create or evaluate a command. .AP char *cmdName in @@ -54,7 +55,7 @@ Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR and \fIobjProc\fR. .AP Tcl_CmdDeleteProc *deleteProc in/out Procedure to call before \fIcmdName\fR is deleted from the interpreter. -This procedure allows for command-specific cleanup. If \fIdeletProc\fR +This procedure allows for command-specific cleanup. If \fIdeleteProc\fR is \fBNULL\fR, then no procedure is called before the command is deleted. .AP int objc in Count of parameters provided to the implementation of a command. @@ -139,7 +140,7 @@ and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the words of the command to be evaluated when execution reaches the trampoline. .PP -\fBTcl_NRCmdSwap allows for trampoline evaluation of a command whose +\fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose resolution is already known. The \fIcmd\fR parameter gives a \fBTcl_Command\fR object (returned from \fBTcl_CreateObjCmd\fR or \fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in @@ -148,7 +149,7 @@ The remaining arguments are as for \fBTcl_NREvalObj\fR. .PP \fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR all accept a \fIflags\fR parameter, which is an OR-ed-together set of -bits to control evaluation. At the present time, the only flag +bits to control evaluation. At the present time, the only supported flag available to callers is \fBTCL_EVAL_GLOBAL\fR. .\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE .\" and TCL_EVAL_NOERR? @@ -180,9 +181,9 @@ consistent with the \fBTcl_NRPostProc\fR data type: .CS typedef int \fBTcl_NRPostProc\fR( - \fBClientData\fR \fIdata\fR[], - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIresult\fR); + \fBClientData\fR \fIdata\fR[], + \fBTcl_Interp\fR *\fIinterp\fR, + int \fIresult\fR); .CE .PP When the trampoline invokes the callback function, the \fIdata\fR @@ -206,22 +207,26 @@ The usual pattern for Tcl commands that invoke other Tcl commands is something like: .PP .CS -int \fITheCmdObjProc\fR( - \fBClientData\fR \fIclientData\fR, - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\fR[]) +int +\fITheCmdObjProc\fR( + ClientData clientData, + Tcl_Interp *interp, + int objc, + Tcl_Obj *const objv[]) { - int \fIresult\fR; - \fBTcl_Obj\fR *\fIobjPtr\fR; + int result; + Tcl_Obj *objPtr; + \fI... preparation ...\fR - \fIresult\fR = \fBTcl_EvalObjEx\fR(\fIinterp\fR, \fIobjPtr\fR, 0); + + result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0); + \fI... postprocessing ...\fR - return \fIresult\fR; + + return result; } -\fBTcl_CreateObjCommand\fR(\fIinterp\fR, "theCommand", - \fITheCmdObjProc\fR, \fIclientData\fR, - \fITheCmdDeleteProc\fR); +\fBTcl_CreateObjCommand\fR(interp, "theCommand", + \fITheCmdObjProc\fR, clientData, TheCmdDeleteProc); .CE .PP To enable a command like this one for trampoline-based evaluation, @@ -245,14 +250,14 @@ a single statement: .PP .CS int -TheCmdNewObjProc - \fBClientData\fR \fIclientData\fR, - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\fR[]) +\fITheCmdNewObjProc\fR( + ClientData clientData, + Tcl_Interp *interp, + int objc, + Tcl_Obj *const objv[]) { - return \fBTcl_NRCallObjProc\fR(\fIinterp, name,\fR - \fITheCmdNRObjProc, clientData, objc, objv\fR); + return \fBTcl_NRCallObjProc\fR(interp, name, + \fITheCmdNRObjProc\fR, clientData, objc, objv); } .CE .PP @@ -261,18 +266,22 @@ and returns to the trampoline requesting command evaluation. .PP .CS int -TheCmdNRObjProc - \fBClientData\fR \fIclientData\fR, - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\fR[]) +\fITheCmdNRObjProc\fR + ClientData clientData, + Tcl_Interp *interp, + int objc, + Tcl_Obj *const objv[]) { + Tcl_Obj *objPtr; + \fI... preparation ...\fR - \fBTcl_NRAddCallback\fR(\fIinterp, TheCmdPostProc,\fR - \fIdata0, data1, data2, data3\fR); - /* \fIdata0 .. data3\fR are up to four one-word items - * to pass to the postprocessing procedure */ - return \fBTcl_NREvalObj\fR(\fIinterp, objPtr, 0\fR); + + \fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR, + data0, data1, data2, data3); + /* \fIdata0 .. data3\fR are up to four one-word items to + * pass to the postprocessing procedure */ + + return \fBTcl_NREvalObj\fR(interp, objPtr, 0); } .CE .PP @@ -281,14 +290,16 @@ upon return from the inner evaluation. .PP .CS int -TheCmdNRPostProc - \fBClientData\fR \fIdata\fR[], - \fBTcl_Interp\fR *\fIinterp\fR, - int \fIresult\fR +\fITheCmdNRPostProc\fR( + ClientData data[], + Tcl_Interp *interp, + int result) { - /* \fIdata[0] .. data[4]\fR are the four words of data + /* \fIdata[0] .. data[3]\fR are the four words of data * passed to \fBTcl_NREvalObj\fR */ + \fI... postprocessing ...\fR + return result; } .CE @@ -306,9 +317,9 @@ of one. The first is for use when no trampoline is yet on the stack, and the second is for use when there is already a trampoline in place. .PP .CS -\fBTcl_NRCreateCommand\fR(\fIinterp\fR, "theCommand", - \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, \fIclientData\fR, - \fITheCmdDeleteProc\fR); +\fBTcl_NRCreateCommand\fR(interp, "theCommand", + \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, clientData, + TheCmdDeleteProc); .CE .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3) |