add_hook


`add_hook`
Prev	IPC	Next

`add_hook`

add_hook — hooks a function to an event.

Synopsis

add_hook (hook_sym, function_sym)

Arguments

hook_sym: One of several symbols used to identify the hook, as listed below.
function_sym: The function that is to run when the event occurs.

Returns

The hooked function (function_sym) that was added.

Description

This function sets up a hook, which is a function that is called when a particular event takes place. The arguments to the function identified by the function_sym are determined by the particular event. A hook function must be defined with the correct number of arguments, or else with optional or variable length arguments. The currently available hooks and the respective events that trigger their functions are as follows:

taskstarted_hook: triggered whenever a task starts.
taskdied_hook: triggered whenever a task dies.
exception_hook: triggered whenever an exception for any point is emitted by a DataHub instance.
echo_hook: triggered whenever an echo for any point is emitted by a DataHub instance.
gc_hook: triggered whenever the garbage collector runs.
The following are related to tracing code executions, but haven't been fully documented.
trace_symbol_hook
trace_entry_hook
trace_exit_hook
breakpoint_hook

One common use of this function is to add the internal taskstarted or taskdied functions, with the taskstarted_hook or taskdied_hook. Whenever a task that is registered with nserve starts or dies, nserve sends a message to all Gamma applications running IPC. Any of these applications that has added the taskstarted_hook or taskdied_hook then runs their corresponding function_sym function.

Example

This example program requires qserve and nserve to be running. It gives the output shown below:

#!/usr/cogent/bin/gamma

//Program: ex_addrunhooks.g
    		
function main ()
{
  init_ipc ("x","x");
  
  add_hook (#taskstarted_hook, #hook_started);
  add_hook (#taskdied_hook, #hook_died);
  
  run_hooks (#taskstarted_hook, "testing start");
  run_hooks (#taskdied_hook, "testing died");
  
  while(t)
    next_event();
}

function hook_started (!a?...=nil)
{
  princ ("Hooked task started: ", a, "\n");
}

function hook_died (!a?...=nil)
{
  princ ("Hooked task died: ", a, "\n");
}

Output from ex_addrunhooks.g at startup:

Hooked task started: (testing start)
Hooked task died: (testing died)

Starting a new Gamma task named mytask...

Gamma> init_ipc("mytask", "myqueue");
t
Gamma>

...elicits this output from ex_addrunhooks.g:

Hooked task started: (mytask default myqueue 0 0 1874 0)

Checking process status with nsnames:

[home/robert]$ nsnames
Name   Domain  Queue    NID PID  
mytask default myqueue  0   1874 
x      default x        0   1873

Terminating mytask elicits this output from ex_addrunhooks.g:

Hooked task died: (mytask default myqueue 0 0 1874 0)