add_hook

Gamma: Version 4.0
Prev |  | Next

# `add_hook`

`add_hook` -- hooks a function to an event.

## Syntax

    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 the Cascade DataHub.

- `echo_hook`: triggered whenever an echo for any point is emitted by the Cascade DataHub.

- `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)

See the Starting Programs section of the Common Functions for Any Program chapter (Tutorial One) in the Cogent Tools Demo and Tutorials book for an example of this function used in context.

## See Also

`run_hooks`, `remove_hook`, `init_ipc`

Prev | Home | Next
IPC | Up | `close_task`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.