Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

HookCore - C Part in the core system
[Hook - A callback system]


Detailed Description

The Hook module connects the core of the library to its outside world by a callback mechanism. Hook functions are to be supplied by the application programmer and will be called at strategic points in the application. For instance, a commonly used hook is HOOK_PRINTF, that handles the output channels (see below).

So hooking the HOOK_PRINTF callback allows you to redefine and redirect the channels. The following callbacks are defined:

As a part of that the output channels are handled here. The following output channels exist:

Note, that the term hook and callback are used mostly as synonyms. (Actually the term hook should be replaced by callback for clarity.)

As oposed to other modules some of the functions in this module are not prefixed by hk as the Coding style dictates. The reason for that lies in the relative importance of this module and some of its functions to the overall system, i.e. cdgPrintf().


Data Structures

struct  HookStruct

Defines

#define CDG_DEBUG   (1L << 9)
#define CDG_DEFAULT   (1L << 10)
#define CDG_ERROR   (1L << 8)
#define CDG_EVAL   (1L << 4)
#define CDG_HINT   (1L << 0)
#define CDG_HOOK   (1L << 7)
#define CDG_INFO   (1L << 1)
#define CDG_PROFILE   (1L << 6)
#define CDG_PROGRESS   (1L << 11)
#define CDG_PROLOG   (1L << 3)
#define CDG_SEARCHRESULT   (1L << 5)
#define CDG_WARNING   (1L << 2)
#define CDG_XML   (1L << 12)
#define HOOK_CNBUILDNODES   0
#define HOOK_EVAL   1
#define HOOK_FLUSH   4
#define HOOK_GETS   7
#define HOOK_GLSINTERACTION   6
#define HOOK_ICINTERACTION   10
#define HOOK_NSSEARCH   2
#define HOOK_PARTIALRESULT   9
#define HOOK_PRINTF   3
#define HOOK_PROGRESS   8
#define HOOK_RESET   5

Typedefs

typedef HookStructHook
typedef void HookFunction ()

Functions

void cdgExecHook (int hookNo,...)
void cdgFlush (void)
void cdgGetString (String buffer, int size)
void cdgPrintf (int mode, String format,...)
void hkCallback (String name, Boolean *var)
void hkFinalize (void)
int hkFindNoOfHook (String name)
void hkInitialize (void)
Boolean hkValidate (String name, String value, Boolean *var)

Variables

Vector hkHooks
Vector hkHooks = NULL
unsigned long int hkVerbosity
unsigned long int hkVerbosity = CDG_DEFAULT | CDG_ERROR | CDG_INFO | CDG_WARNING | CDG_SEARCHRESULT


Define Documentation

#define CDG_DEBUG   (1L << 9)
 

identification of the DEBUG channel. This message increases the normal output verbosity by offering debug information. Definition at line 167 of file hook.h.

Referenced by cmdStatus(), cnBuildEdges(), cnBuildLv(), cnBuildNodes(), cnBuildUpdateArcs(), cnOptimizeNet(), cnOptimizeNode(), cnPrintActiveLVs(), cnSortNodes(), cnTag(), comMake(), embedChunk(), evalBinary(), evalUnary(), findChunk(), getCategories(), getChunks(), getFakeChunksAt(), hkInitialize(), initRealChunker(), lgPartitions(), mergeChunk(), postProcessChunks(), and scSetScore().

#define CDG_DEFAULT   (1L << 10)
 

identification of the DEFAULT channel. Unclassified messages of messages that should only be supressed in very rare cases are emitet on the DEFAULT channel. Definition at line 174 of file hook.h.

Referenced by cmdAnnotation(), cmdConstraint(), cmdDistance(), cmdEdges(), cmdHelp(), cmdHierarchy(), cmdHook(), cmdLevel(), cmdLexicon(), cmdLicense(), cmdNet(), cmdNonSpecCompatible(), cmdSection(), cmdStatus(), cmdVersion(), cmdWordgraph(), comApprove(), comCompile(), commandLoop(), and hkInitialize().

#define CDG_ERROR   (1L << 8)
 

identification of the ERROR channel. This channel transmits messages about unexpected events that lead to an abortion of further computation. Compare to WARNING. Definition at line 160 of file hook.h.

Referenced by cdgExecHook(), cdgPrintf(), chunkerChunk(), chunkerCommandValidate(), chunkerNew(), cmdAnno2Parse(), cmdAnnos2prolog(), cmdAnnotation(), cmdChunk(), cmdCompareParses(), cmdCompile(), cmdConstraint(), cmdDistance(), cmdEdges(), cmdHelp(), cmdHierarchy(), cmdHook(), cmdIncrementalCompletion(), cmdInputwordgraph(), cmdISearch(), cmdLevel(), cmdLevelsort(), cmdLoad(), cmdLs(), cmdNet(), cmdNetdelete(), cmdNetsearch(), cmdNewnet(), cmdNonSpecCompatible(), cmdParsedelete(), cmdParses2prolog(), cmdPrintParse(), cmdPrintParses(), cmdRenewnet(), cmdReset(), cmdSection(), cmdSet(), cmdShowlevel(), cmdStatus(), cmdTagger(), cmdTesting(), cmdUseconstraint(), cmdUselevel(), cmdUseLexicon(), cmdVerify(), cmdWeight(), cmdWordgraph(), cmdWriteAnno(), cmdWriteNet(), cmdWriteParses(), cmdWriteWordgraph(), comApprove(), comCompareAllLvPairs(), comCompareAllLvs(), comCompareLvs(), comCompareNets(), comCompareWithContext(), comCompile(), comFinitGrammar(), comInitGrammar(), comLoad(), comMake(), commandEval(), computeNoOfPathsFromStart(), computeNoOfPathsToEnd(), dbClose(), dbGetEntries(), dbLoadEntries(), dbOpen(), dbOpenIndexFile(), getChunks(), hkInitialize(), initChunker(), initFakeChunker(), initRealChunker(), lgAreDeletableNodes(), lgCompatibleNodes(), lgDistanceOfNodes(), parseGetGrapheme(), scSetScore(), smDelete(), smGetFlag(), smGetScore(), smSetAllFlags(), smSetFlag(), smSetScore(), terminateChild(), timerElapsed(), and unlock_tree().

#define CDG_EVAL   (1L << 4)
 

identification of the EVAL channel.

Todo:
The EVAL channel is bogus and never used.
Definition at line 130 of file hook.h.

Referenced by cmdStatus(), and hkInitialize().

#define CDG_HINT   (1L << 0)
 

identification of the HINT channel.

Todo:
The HINT channel is bogus and never used.
Definition at line 103 of file hook.h.

Referenced by cmdStatus(), and hkInitialize().

#define CDG_HOOK   (1L << 7)
 

global hook flag. This flag switches on/off the complete hook system.

Todo:
By no means this is an output channel. This define should be removed and replaced with a proper variable that is altered by the hook command.
Definition at line 153 of file hook.h.

Referenced by cmdHook(), cmdStatus(), cnBuildNodes(), evalBinaryConstraint(), evalConstraint(), and evalUnaryConstraint().

#define CDG_INFO   (1L << 1)
 

identification of the INFO channel. Most of the output of the CDG library is tagged as INFO. A message to the INFO channel is informal. Definition at line 110 of file hook.h.

Referenced by cdgDeleteComputed(), chunkerChunk(), cmdAnno2Parse(), cmdAnnos2prolog(), cmdChunk(), cmdCompile(), cmdHook(), cmdIncrementalCompletion(), cmdInputwordgraph(), cmdISearch(), cmdLevelsort(), cmdLexicon(), cmdLoad(), cmdNetsearch(), cmdNewnet(), cmdNonSpecCompatible(), cmdParsedelete(), cmdParses2prolog(), cmdRenewnet(), cmdSet(), cmdShowlevel(), cmdStatus(), cmdUseconstraint(), cmdUselevel(), cmdVerify(), cmdWeight(), cnCallback(), cnPrintActiveLVs(), cnPrintInfo(), cnPrintParses(), cnTag(), cnUnaryPruning(), comLoad(), comMake(), comTranslate(), cvAnalyse(), cvPrint(), dbLoad(), dbLoadAll(), dbLoadEntries(), evalChunker(), hkInitialize(), and lgNewFinal().

#define CDG_PROFILE   (1L << 6)
 

identification of the PROFILE channel. This channel is used to emit profiling information, that is time statistics on computations. Definition at line 144 of file hook.h.

Referenced by cmdChunk(), cmdIncrementalCompletion(), cmdISearch(), cmdNewnet(), cmdStatus(), cnBuildEdges(), cnBuildNodes(), and hkInitialize().

#define CDG_PROGRESS   (1L << 11)
 

identification of the PROGRESS channel. Messages about progress are emited on this channel and might be redirected over the HOOK_PROGRESS callback. Definition at line 181 of file hook.h.

Referenced by cdgPrintf(), cmdAnno2Parse(), cmdStatus(), dbLoadAll(), and hkInitialize().

#define CDG_PROLOG   (1L << 3)
 

identification of the PROLOG channel.

Todo:
The PROLOG channel is bogus and never used.
Definition at line 124 of file hook.h.

Referenced by cmdStatus(), and hkInitialize().

#define CDG_SEARCHRESULT   (1L << 5)
 

identification of the SEARCHRESULT channel. Results in a parser are emited on this channel. All parsing falvours should obey to this channel semantics. Most of them do. Definition at line 137 of file hook.h.

Referenced by cmdNetsearch(), cmdStatus(), and hkInitialize().

#define CDG_WARNING   (1L << 2)
 

identification of the WARNING channel. A message to this channel informs about an unexpected situation. Operations continue. If a normal continuation is not possible the message should be emitted on the ERROR channel. Definition at line 118 of file hook.h.

Referenced by cdgAgInsert(), cdgPrintf(), cmdAnno2Parse(), cmdLs(), cmdNewnet(), cmdStatus(), cnBuild(), cnBuildFinal(), cnDelete(), cnFindNode(), cnOptimizeNode(), cnPrintInfo(), comApprove(), commandLoop(), dbAvailable(), evalBinaryConstraint(), evalChunker(), evalConstraint(), evalFormula(), evalTerm(), evalUnaryConstraint(), evalValidateEvalMethod(), getCategory(), getChunks(), getNextArgument(), hkInitialize(), lgDeleteNode(), lgDeleteNodes(), lgMostProbablePath(), lgNewFinal(), lgNewIter(), lgSimultaneous(), peekValue(), and terminateChild().

#define CDG_XML   (1L << 12)
 

identification of the PROGRESS channel. All xml output goes in this channel. See the write module for more infofmation on xml output. Definition at line 188 of file hook.h.

Referenced by cmdStatus(), commandEval(), and hkInitialize().

#define HOOK_CNBUILDNODES   0
 

callback after building constraintnodes. Definition at line 43 of file hook.h.

Referenced by cnBuildNodes(), and hkInitialize().

#define HOOK_EVAL   1
 

callback after evaluation of constraints. Definition at line 48 of file hook.h.

Referenced by evalBinaryConstraint(), evalConstraint(), evalUnaryConstraint(), hkInitialize(), and hooker_init().

#define HOOK_FLUSH   4
 

callback for flushing the output channels. Definition at line 63 of file hook.h.

Referenced by cdgFlush(), hkInitialize(), hooker_init(), and logFlush().

#define HOOK_GETS   7
 

callback in to get a string from the user. Definition at line 79 of file hook.h.

Referenced by cdgGetString(), hkInitialize(), and hooker_init().

#define HOOK_GLSINTERACTION   6
 

callback for user interaction in the gls module. Definition at line 74 of file hook.h.

Referenced by hkInitialize(), and hooker_init().

#define HOOK_ICINTERACTION   10
 

callback for user interaction in the incrementalcompletion module. Definition at line 94 of file hook.h.

Referenced by hkInitialize(), and hooker_init().

#define HOOK_NSSEARCH   2
 

callback in netsearching. Definition at line 53 of file hook.h.

Referenced by hkInitialize(), and hooker_init().

#define HOOK_PARTIALRESULT   9
 

callback to hand over partial results. Definition at line 89 of file hook.h.

Referenced by hkInitialize(), and hooker_init().

#define HOOK_PRINTF   3
 

callback for printfing. Definition at line 58 of file hook.h.

Referenced by cdgPrintf(), hkInitialize(), hooker_init(), logFlush(), and logPrintf().

#define HOOK_PROGRESS   8
 

callback to indicate progress in a heavy computation. Definition at line 84 of file hook.h.

Referenced by cdgPrintf(), hkInitialize(), and hooker_init().

#define HOOK_RESET   5
 

notification that parses, constraint nets etc. have become invalid because of grammar changes. Definition at line 69 of file hook.h.

Referenced by cdgDeleteComputed(), hkInitialize(), and hooker_init().


Typedef Documentation

typedef HookStruct* Hook
 

type of a Hook Definition at line 216 of file hook.h.

Referenced by cdgExecHook(), cdgFlush(), cdgGetString(), cdgPrintf(), cmdHook(), evalHookHandle(), getHookCmd(), getsHookHandle(), glsInteractionHookHandle(), hkFindNoOfHook(), hkInitialize(), hook_completion_function(), hooker_init(), ICinteractionHookHandle(), initHookResult(), logFlush(), netsearchHookHandle(), partialResultHookHandle(), progressHookHandle(), resetHookHandle(), setHookCmd(), and tclHookHandle().

typedef void HookFunction()
 

type of a callback function. This function is installed into a callback hook and executed whenever this callback is triggered. This is only a indicator definition without any grants on the arguments. But be aware of the arguments that are actually needed by every callback. Definition at line 201 of file hook.h.

Referenced by hkInitialize(), and hooker_init().


Function Documentation

void cdgExecHook int  hookNo,
  ...
 

execute a defined callback. This is the standard way to call a hook. If the corresponding HookStruct::active is set, its HookStruct::count is increased and its HookStruct::function is called handing over a pointer to the HookStruct we are executing and the entire va_list passed to this function. For example, cdgExecHook(HOOK_PARTIALRESULT, parse) is executing HookStruct::function(hook, parse).

Parameters:
hookNo the identifier of the hook to be called, e.g. HOOK_PROGRESS
Definition at line 306 of file hook.c.

References HookStruct::active, CDG_ERROR, cdgPrintf(), HookStruct::count, HookStruct::function, hkHooks, Hook, and HookStruct::name.

Referenced by cdgDeleteComputed(), cnBuildNodes(), evalBinaryConstraint(), evalConstraint(), and evalUnaryConstraint().

void cdgFlush void   ) 
 

default flush callback. This is the default callback for HOOK_FLUSH. If no hook is installed, i.e. HookStruct::function is NULL, then fflush is called. In addition writeXmlFlush() is called to sync the CDG_XML output channel. Definition at line 454 of file hook.c.

References HookStruct::count, HookStruct::function, hkHooks, Hook, and HOOK_FLUSH.

Referenced by cdgPrintf(), cnBuildEdges(), cnBuildIter(), comApprove(), comMake(), commandEval(), and comTranslate().

void cdgGetString String  buffer,
int  size
 

default get string callback. This function gets one newline-terminated chunk of console input from the user. Up to size characters are transferred into buffer. For this purpose, HOOK_GETS is executed. It this hook has no associated function, fgets() is called instead with an additional argument of stdin. This provides a transparent way of reading input from a user. (Note that the normal interaction with the shell of the cdgp parser uses a different and non-transparent input routine.) Definition at line 375 of file hook.c.

References HookStruct::count, HookStruct::function, hkHooks, Hook, and HOOK_GETS.

void cdgPrintf int  mode,
String  format,
  ...
 

output channel router. This function takes care of routing messages to appropriate output channels. The first argument mode defines bitwise the channels this message is to be routed to. The rest of the arguments is passed to the HOOK_PRINTF in printf mannor (so see the manual pages for printf). We use HOOK_PROGRESS exclusive here when the hkVerbosity contains the CDG_PROGRESS flag and only HOOK_PRINTF otherwise. If we are producing xml output and the CDG_WARNING or CDG_ERROR channel is used, then the message doubled according to the cdg-logfile.dtd by writeXmlVaNotification(). Definition at line 403 of file hook.c.

References CDG_ERROR, CDG_PROGRESS, CDG_WARNING, cdgFlush(), HookStruct::count, HookStruct::function, hkHooks, hkVerbosity, Hook, HOOK_PRINTF, HOOK_PROGRESS, and NULL.

Referenced by bPrint(), cdgAgInsert(), cdgDeleteComputed(), cdgExecHook(), chunkerChunk(), chunkerCommandValidate(), chunkerNew(), chunkerPrintChunks(), cmdAnno2Parse(), cmdAnnos2prolog(), cmdAnnotation(), cmdChunk(), cmdCompareParses(), cmdCompile(), cmdConstraint(), cmdDistance(), cmdEdges(), cmdHelp(), cmdHierarchy(), cmdHook(), cmdIncrementalCompletion(), cmdInputwordgraph(), cmdISearch(), cmdLevel(), cmdLevelsort(), cmdLexicon(), cmdLicense(), cmdLoad(), cmdLs(), cmdNet(), cmdNetdelete(), cmdNetsearch(), cmdNewnet(), cmdNonSpecCompatible(), cmdParsedelete(), cmdParses2prolog(), cmdPrintParse(), cmdPrintParses(), cmdRenewnet(), cmdReset(), cmdSection(), cmdSet(), cmdShowlevel(), cmdStatus(), cmdTagger(), cmdTesting(), cmdUseconstraint(), cmdUselevel(), cmdUseLexicon(), cmdVerify(), cmdVersion(), cmdWeight(), cmdWordgraph(), cmdWriteAnno(), cmdWriteNet(), cmdWriteParses(), cmdWriteWordgraph(), cnBuild(), cnBuildEdges(), cnBuildFinal(), cnBuildLv(), cnBuildNodes(), cnBuildUpdateArcs(), cnCallback(), cnDelete(), cnFindNode(), cnOptimizeNet(), cnOptimizeNode(), cnPrint(), cnPrintActiveLVs(), cnPrintEdge(), cnPrintInfo(), cnPrintNode(), cnPrintParses(), cnSortNodes(), cnTag(), cnUnaryPruning(), comApprove(), comCompareAllLvPairs(), comCompareAllLvs(), comCompareLvs(), comCompareNets(), comCompareWithContext(), comCompile(), comFinitGrammar(), comInitGrammar(), comLoad(), comMake(), commandEval(), commandLoop(), computeNoOfPathsFromStart(), computeNoOfPathsToEnd(), comTranslate(), cvAnalyse(), cvPrint(), dbAvailable(), dbClose(), dbGetEntries(), dbLoad(), dbLoadAll(), dbLoadEntries(), dbOpen(), dbOpenIndexFile(), embedChunk(), evalBinary(), evalBinaryConstraint(), evalChunker(), evalConstraint(), evalFormula(), evalTerm(), evalUnary(), evalUnaryConstraint(), evalValidateEvalMethod(), findChunk(), getCategories(), getCategory(), getChunks(), getFakeChunksAt(), getNextArgument(), initChunker(), initFakeChunker(), initRealChunker(), lgAreDeletableNodes(), lgCompatibleNodes(), lgDeleteNode(), lgDeleteNodes(), lgDistanceOfNodes(), lgMostProbablePath(), lgNewFinal(), lgNewIter(), lgPartitions(), lgPrint(), lgPrintNode(), lgSimultaneous(), mergeChunk(), parseGetGrapheme(), peekValue(), postProcessChunks(), printChunk(), scSetScore(), smDelete(), smGetFlag(), smGetScore(), smSetAllFlags(), smSetFlag(), smSetScore(), terminateChild(), timerElapsed(), and unlock_tree().

void hkCallback String  name,
Boolean *  var
 

monitor access to variables in this module.

This function is installed using setRegister() in the hkInitialize() function of this module. When a variable is changed hkCallback() is called handling appropriate sideeffects depending on the new variable value. Right now only the variable xml is handled here.

Switching on xml writes an appropriate xml header to the CDG_XML channel. Switching off xml finishes all open xml tags. See the write module for more information on the xml output channel. Definition at line 141 of file hook.c.

Referenced by hkInitialize().

void hkFinalize void   ) 
 

finalization of this module. After this call the CDG library is nearly shut down. That's why this finalizer is to be called at last after calling the finalizer of all other modules. Definition at line 286 of file hook.c.

References hkHooks.

Referenced by cdgFinalize().

int hkFindNoOfHook String  name  ) 
 

get the numerical identifier of a named hook.

Parameters:
name the name of a known hook
Returns:
the numerical identifier on success or -1 of no hook of that name exists.
Definition at line 347 of file hook.c.

References FALSE, hkHooks, Hook, and HookStruct::name.

Referenced by cmdHook(), getHookCmd(), and setHookCmd().

void hkInitialize void   ) 
 

initialization of the hook module. This function must be called before the CDG library is functional. Definition at line 156 of file hook.c.

References HookStruct::active, CDG_DEBUG, CDG_DEFAULT, CDG_ERROR, CDG_EVAL, CDG_HINT, CDG_INFO, CDG_PROFILE, CDG_PROGRESS, CDG_PROLOG, CDG_SEARCHRESULT, CDG_WARNING, CDG_XML, HookStruct::cmd, HookStruct::count, FALSE, HookStruct::function, hkCallback(), hkHooks, hkValidate(), hkVerbosity, Hook, HOOK_CNBUILDNODES, HOOK_EVAL, HOOK_FLUSH, HOOK_GETS, HOOK_GLSINTERACTION, HOOK_ICINTERACTION, HOOK_NSSEARCH, HOOK_PARTIALRESULT, HOOK_PRINTF, HOOK_PROGRESS, HOOK_RESET, HookFunction, HookStruct::name, HookStruct::no, NULL, and TRUE.

Referenced by cdgInitialize().

Boolean hkValidate String  name,
String  value,
Boolean *  var
 

validate access to variables in this module.

This function is installed using setRegister() in the hkInitialize() function of this module. It is monitoring the access to the variable xml being registered in hkInitialize(). Definition at line 113 of file hook.c.

References FALSE, and TRUE.

Referenced by hkInitialize().


Variable Documentation

Vector hkHooks
 

This Vector holds all defined hooks. It is initialized by the function hkInitialize(). After that, the symbolic constants can be used to execute any of the hooks. Definition at line 88 of file hook.c.

Referenced by cdgExecHook(), cdgFlush(), cdgGetString(), cdgPrintf(), cmdHook(), getHookCmd(), hkFinalize(), hkFindNoOfHook(), hkInitialize(), hook_completion_function(), hooker_init(), logFlush(), logPrintf(), and setHookCmd().

Vector hkHooks = NULL
 

This Vector holds all defined hooks. It is initialized by the function hkInitialize(). After that, the symbolic constants can be used to execute any of the hooks. Definition at line 88 of file hook.c.

Referenced by cdgExecHook(), cdgFlush(), cdgGetString(), cdgPrintf(), cmdHook(), getHookCmd(), hkFinalize(), hkFindNoOfHook(), hkInitialize(), hook_completion_function(), hooker_init(), logFlush(), logPrintf(), and setHookCmd().

unsigned long int hkVerbosity
 

bitwise encoding of active output channels.

This variable controls the currently active output channels. All output is performed by the function cdgPrintf(), whose first argument is a bitwise encoding denoting the output channels (e.g. CDG_INFO, CDG_ERROR, or CDG_DEBUG output) to which a message is to be routed.

All messages tagged with a bit that is not set in hkVerbosity are suppressed. Definition at line 101 of file hook.c.

Referenced by cdgPrintf(), cmdHook(), cmdNetsearch(), cmdStatus(), cnBuildNodes(), cnPrintInfo(), cnSortNodes(), cnTag(), comApprove(), commandEval(), dbLoadEntries(), evalBinaryConstraint(), evalConstraint(), evalUnaryConstraint(), and hkInitialize().

unsigned long int hkVerbosity = CDG_DEFAULT | CDG_ERROR | CDG_INFO | CDG_WARNING | CDG_SEARCHRESULT
 

bitwise encoding of active output channels.

This variable controls the currently active output channels. All output is performed by the function cdgPrintf(), whose first argument is a bitwise encoding denoting the output channels (e.g. CDG_INFO, CDG_ERROR, or CDG_DEBUG output) to which a message is to be routed.

All messages tagged with a bit that is not set in hkVerbosity are suppressed. Definition at line 101 of file hook.c.

Referenced by cdgPrintf(), cmdHook(), cmdNetsearch(), cmdStatus(), cnBuildNodes(), cnPrintInfo(), cnSortNodes(), cnTag(), comApprove(), commandEval(), dbLoadEntries(), evalBinaryConstraint(), evalConstraint(), evalUnaryConstraint(), and hkInitialize().


CDG 0.95 (20 Oct 2004)