13.3. Cogent IPC

13.3.2.1. Cogent IPC Messages

The Cogent IPC layer provides a messaging protocol that is easier to use and different in format from raw QNX 4 send/receive/reply.

Messages between Cogent IPC-enabled tasks are very similar to function calls. A message is constructed and sent, and the task on the other end evaluates the message. The return value of the evaluation of the message is transmitted to the originating task in the reply.

Consider two Gamma modules using the following code:

Task A:

    #!/usr/cogent/bin/gamma
    init_ipc("task_a");
    
    while (t)
    {
        next_event();
    }
    		

Task B:

    #!/usr/cogent/bin/gamma
    init_ipc("task_b");
    
    function ask_taska_date ()
    {
        local result,tp;
        if (tp = locate_task("task_a",nil))
            result = send(tp,#date());
        else
            result = "could not locate task A";
    }
    
    every(1.0,#princ(ask_taska_date(),"\n"));
    
    while (t)
    {
        next_event();
    }
    		  

Of specific note in this example is the format of the message in the send function. The first argument to the Cogent IPC function send is a task. The locate_task function, along with the nserve module provides the name lookup. The second argument is an expression for the receiver to evaluate. For simple send's an unevaluated Gamma expression (using #) will suffice. For more complex send's, such as when a partially evaluated list of arguments need to be passed, the format of the send command should be Lisp.

This code gives a good example of using the Cogent IPC layer as an RPC (Remote Procedure Call) mechanism.

To use the Cogent IPC layer for transferring data between tasks, use the Lisp expression for assignment: setq. An example is:

Task C:

    #!/usr/cogent/bin/gamma
    init_ipc("task_c");
    
    add_set_function(#x,#princ("Task C reports x=",x,"\n"));
    
    while (t)
    {
        next_event();
    }
    		

Task D:

    #!/usr/cogent/bin/gamma
    init_ipc("task_d");
    
    function inc_x ()
    {
        local result,tp;
        x++;
        if (tp = locate_task("task_c",nil))
            result = send(tp,list(#setq, #x, x));
    }
    
    x = 0;
    every(0.1,#inc_x());
    
    while (t)
    {
        next_event();
    }
    		  

In this example task C sets up a set_function before starting its event loop. The set function will print out the value of x if it changes. Task D initializes x to 0 and then starts a timer to run every tenth of a second to increment x and send setq expressions to task C.

    (setq x 1)
(setq x 2)
(setq x 3)
(setq x 4)
    		  

The setq function is evaluated in task C. Any side effects of the function, for example the setting of the variable x, happens in task C. The return value of the function is the content of the reply message. The return value of the send function can be found by evaluating the 'result' variable in the inc_x function.

Consider the inc_x function re-written as:

    function inc_x ()
    {
        local result,tp;
    
        x++;
    
        if (tp = locate_task("task_c",nil))
        {
            result = send(tp,list(#setq, #x, x));
            princ("task D result of send: ",result,"\n");
        }
    }
    		  

13.3.2.2. Asynchronous Messages

Consider two tasks that wish to communicate: task E and task F. Task E is a time sensitive task that needs to deliver a package of data to task F. Task E cannot take the chance that task F will accept its data immediately and issue a reply so that it may continue with its own jobs. In short, a synchronous send compromises task E's job because it must wait for task F to respond before proceeding.

To send data asynchronously from task E to task F, a queue is used. Data is sent from task E to the queue. The queue responds immediately to task E, freeing it up to continue. Then a proxy, a special non-blocking message, is sent from the queue to task F. Upon receipt of the proxy, task F knows that the queue contains data for it. When task F is ready it asks the queue for the data.

With some small changes, the example from the previous section can be changed from synchronous messaging to asynchronous, as follows:

Task E:

    #!/usr/cogent/bin/gamma
    init_ipc("task_e","task_e_q");
    
    add_set_function(#x,#princ("Task E reports x=",x,"\n"));
    
    while (t)
    {
        next_event();
    }
    		

    #!/usr/cogent/bin/gamma
    init_ipc("task_f","task_f_q");
    
    function inc_x ()
    {
        local result,tp;
    
        x++;
    
        if (tp = locate_task("task_e",nil))
        {
            result = send_async(tp,list(#setq, #x, x));
            princ("task F result of send: ",result,"\n");
        }
    }
    
    x = 0;
    every(0.1,#inc_x());
    
    while (t)
    {
        next_event();
    }
    		  

13.3.2.3. Pseudo-Asynchronous Messages

For situations where the qserve program is not running and an asynchronous non-blocking IPC call is required then Gamma pseudo-asynchronous IPC call can be used.

The isend function sends a message between two Cogent IPC enabled tasks. Immediately upon receipt of the message, the receiver replies that the message was received. The return value of the received message is not sent back.

13.3.2.4. Task Started & Death Notification

When a task registers a name with nserve it can thereafter receive information regarding any other nserve registered task that starts or stops.

This is done by defining two functions with specific names, each within their respective code, to handle this information. The functions are:

    function taskstarted_hook (name, queue, domain, node, id);
    		

    function taskdied_hook (name, queue, domain, node, id);
    		  

13.3.2.5. Automatic Handling of QNX 4 receive and reply

The following Gamma functions automatically handle QNX 4 receive/reply:

• PtMainLoop

• next_event

• next_event_nb

• flush_events

13.3.2.6. IPC Initialization

Before any form of Cogent interprocess communication occurs there must be a call to the init_ipc function. This function opens the channels of communications between Gamma and other tasks powered by Gamma, Cascade Connect, or other Cogent products. With this function you determine your task's name and optionally its queue name and domain.

A program's name is the string registered with the nserve program. Gamma names and queue names for tasks should be unique on the network. A program's queue name is the name of the queue that is registered if it wants to participate in asynchronous communication using Cogent's qserve utilities. The domain name is the name of the default Cascade DataHub domain from which to read and write points.

It is typical to find the init_ipc function called within the first few calls in the program. Here's an example:

    #!/usr/local/bin/gamma
    require_lisp("PhotonWidget");
    require_lisp("PhabTemplate");
    
    myname = car(argv);
    init_ipc("myname");
    		  

13.3.2.7. Locating Tasks

Using Gamma's IPC communications protocol, a task can be located by name or by id. This protocol allows for synchronous, asynchronous, and semi-asynchronous communications between Gamma, SCADALisp, and other Cogent products such as Cascade Connect and the Cascade DataHub.

Locating a task by name can be done with the locate_task function. This is similar to using the qnx_name_locate function except that, since nserve's names are intended to be unique on a network the node number need not be specified.

    marko:/home/marko$ gamma -q
    Gamma> init_ipc("locate_test");
    t
    Gamma> tp = locate_task("cadsim",nil);
    #< Task:13424 >
    		  

13.3.2.8. Transmitting Character Strings

The send_string and send_string_async functions are used to format a message to be sent to a non-Cogent IPC task. These functions will accept a string (text surrounded by quotes) as a parameter, and will send the contents of the string without the enclosing quotes. Note that the normal send function will send the enclosing quotes as part of the message.