5         Servant Module

In NodeBrain terminology, a servant is a program that communicates with NodeBrain via stdin and/or stdout, or that is spawned by NodeBrain to perform a specific action.  A servant may run as a child process of NodeBrain, or may pipe to NodeBrain’s stdin or from NodeBrain’s stdout. This topic is covered in the NodeBrain User Guide and under the servant prefix command (“-” or “=”) in the NodeBrain Language Reference.

The servant module, like the servant command, makes it easy for programmers to develop in their favorite programming languages when interfacing to NodeBrain rules.  Scripting languages like Perl are convenient for creating servants.  You should only consider writing new NodeBrain skill modules when a problem can not be solved as well by writing a servant.

5.1        Servant Module vs. Servant Command

Servants defined using the servant skill module differ from those defined by the servant command (“-” or “=”) in the following ways.

1)     Rules can send messages to a servant defined by this skill module on stdin in addition to accepting commands on the servant’s stdout.

2)     Servants defined by this skill module are not enabled (spawned) until NodeBrain enters a server mode (servant or agent).  This is necessary in the case of daemons (-d) because the NodeBrain process terminates when it spawns itself as a daemon.  Any processes started before entering daemon mode are orphaned and no longer able to communicate on stdin or stdout.  This is also helpful for other server modes (e.g. servant) because it enables all the startup rules to be fully defined before a servant starts generating commands.

3)     In the future, servants defined by this skill module may be disabled, enabled, stopped, and restarted.  This is possible because they have a name that can be used as a reference.  The servant command (“-“ and “=”) only identifies a servant by process id (PID), and although the PID is displayed and can be referenced in shell commands like KILL, the PID is not captured in a way that it can be referenced by NodeBrain rules.

5.2        Servant Definition

A servant is defined as an expert, where the foreign text includes the full syntax of the servant command (“-” or “=”).

5.3        Sending Servant Messages

Once NodeBrain is running in a server mode (e.g. agent/daemon/service or servant), you may pass messages to a servant using an expert command.  Suppose we define a Perl script named servant.pl as a servant named servant.

          define servant expert servant:|=:./servant.pl

Once in server mode, we can pass a message to servant.pl on stdin as follows.

          servant:message

This is how we pass messages to any expert.  In this case, the servant skill module simply forwards all messages to the specified servant program on stdin.

5.4        Receiving Servant Messages

Messages received from a servant are NodeBrain commands, and are automatically interpreted in the servant’s context.  This is no different than receiving messages from a servant command (“-:” or “=:”).  In both cases the messages are interpreted as NodeBrain commands within the context in which they are specified.

Let’s look at a trivial example.  Suppose our servant.pl looks like this.

#!/usr/bin/perl

use FileHandle;

STDOUT->autoflush(1);  # flush stdout as soon as we write to it

while(<>){

   if(/^on$/){print(“assert status=1;\n”);}

   elsif(/^off$/){print(“assert status=0;\n”);}

   else{print(“assert ?status;\n”);}

   } 

Now let’s define the following NodeBrain daemon script and call it servant.nb.

#!/usr/local/bin/nb –d

set log=”servant.log”;

-cp /dev/null servant.txt

define taylor   expert servant:=:tail –f servant.txt

define servant expert servant:|=:./servant.pl

servant. define hello on(.status=1):-echo “hi”

The following commands will cause our daemon to echo “hi” to the log file twice.

$ ./servant.nb

$ echo “servant:on” >> servant.txt

$ echo “servant:off” >> servant.txt

$ echo “servant:on” >> servant.txt

The servant we named “taylor” uses the tail command to input anything we write to servant.txt.  We emptied it out in the line before the servant definition to prevent tail from giving us old commands from a previous session.  When we echo the NodeBrain command (e.g. “servant:on”) to servant.txt, tail sends them to the servant skill module, which passes them on to the NodeBrain interpreter.  These commands happen to address our second servant, the one executing our servant.pl script.  The values of “on”, “off” and “on” are sent to this script on stdin.  The servant.pl script simply translates these messages into NodeBrain commands that set a value for the “status” term.  When status is set to 1, our “hello” rule fires.

Obviously our servant.pl script in this example isn’t giving us any information we don’t already know, so it is of little or no value.  We could have just echoed “servant.status=1;” to servant.txt in place of “servant:on”.  But our goal here is just to illustrate the servant interface.  It should not be difficult to imagine more realistic situations where you send messages to a servant instructing it when to provide information and/or what information to provide.  For example, the servant could check to see if a process is running or how much space is available in a file system.  Servants just need to know how to perform a function or get some information.  The NodeBrain rules decide how to respond to the information provided and when specific actions are appropriate.

5.5        Running Multiple NodeBrain Processes

The servant module can run NodeBrain (nb) in a new process the same why it runs servant programs and scripts.  The servant module’s support for two-way message communication between processes enables a NodeBrain application to be divided up into multiple processes.  When you define a servant that executes NodeBrain, messages sent to stdin and received from stdout are all NodeBrain commands.  This allows the processes to share information and make decisions or take actions as a service to each other.

When NodeBrain is run as a servant to another NodeBrain process, we use the –s (servant) option if we want the child to run as a server.  We use the “=” option instead if we want the child to operate in batch mode. 

The NodeBrain Language Reference provides a description of NodeBrain options and the full syntax of the servant command (“-” or “=”) which is critical to understanding the syntax used by the servant module.

Copyright © 2003-2006 The Boeing Company