Manipulating Agents

 

    Glish provides the following functions for manipulating agent values:

create_agent()
    returns a new agent value that can be used in subsequent whenever and send statements. That is, the agent value can be sent events and you can set up whenever's to deal with receiving these events.

For example,  

    a := create_agent()
    a->hi( "how are you?" )

    whenever a->hi do
        print $value

will print "how are you?". I am interested in hearing whether users find create_agent() itself more useful than using subsequences (§ 7.12, page ), which provide a more structured interface to dealing with agent's.

client(command,
..., host=F, input=F, suspend=F, ping=F, async=F)    creates a Glish client corresponding to the given command and arguments. See § 7.8.1, page , for details.

shell(command,
..., host=F, input=F, suspend=F, ping=F, async=F)      either executes a Bourne shell command and returns a string representation of its output (if async=F), or creates an asynchronous shell client that can be sent stdin and EOF events and that in turn generates stdout events. The first of these is discussed in § 4.9, page , and the second in § 7.8.2, page .

sync(c)
   synchronizes the Glish script's execution with that of client c. The call to sync() does not return until client c has processed all events/requests previously sent to it.

relay(src,
src_name, ref dest, dest_name="*")   relays every src_name generated by the agent src to the agent dest, renaming the event to dest_name. If dest_name is "*" (the default) then src_name is used.

For example,  

    relay(a, "ready", b, "compute")

relays each of a's ready events to b, renaming them compute, and

    relay(a, "ready", b)

relays ready events generated by a to b, keeping the event's name.

relay_all(src, ref dest)
    relays every event from src to dest; it is equivalent to:

    whenever src->* do
        dest->[$name]($value)

birelay_event(ref
agent1, ref agent2, name)     relays any ``name" event generated by either agent1 or agent2 to the other agent. Thus it is equivalent to:

    relay( agent1, name, agent2 )
    relay( agent2, name, agent1 )

birelay_all(ref
agent1, ref agent2)     relays every event generated by either agent1 or agent2 to the other agent. It is equivalent to:

    relay_all( agent1, agent2 )
    relay_all( agent2, agent1 )

current_whenever()
      returns an index identifying the whenever statement whose body is currently (or was last) executed in response to an event. This index has type integer and is suitable for use in an activate or deactivate statement (§ 7.5.4, page ) for controlling the activity of the whenever statement.

For example, suppose that client a generates both b and c events, and that we want to respond to b events only as long as we haven't received a c event. We could use the following:

    whenever a->b do
        {
        do_b_stuff()
        w := current_whenever()
        }

    whenever a->c do
        {
        do_c_stuff()
        deactivate w    # turn off a->b
        }

This example actually has a bug: if a generates a c event before any b events, then w will not be defined when executing the deactivate statement, resulting in an error. See the discussion of last_whenever_executed() below for a bug-free example.

last_whenever_executed()
      returns an index identifying the most recently-executed whenever statement. Here, ``executed'' refers to execution of the whenever statement itself (which ``activates'' the whenever), and not its body.

As with current_whenever(), this index has type integer and is suitable for use in an activate or deactivate statement (§ 7.5.4, page ). The example used above in describing current_whenever() can instead be written as:  

    whenever a->b do
        {
        do_b_stuff()
        }

    w := last_whenever_executed()

    whenever a->c do
        {
        do_c_stuff()
        deactivate w    # turn off a->b
        }

active_agents()
      returns a record array listing the currently active agents. For example, the following:

    agents := active_agents()

    for ( i in 1:len(agents) )
        {
        a := ref agents[i]
        if ( has_field(a, "locked") )
            a->clear_lock()
        }

will send a clear_lock event to each agent whose agent record has a locked field (presumably due to a previously-received locked event).

Note that the system global variable (§ 9.11, page ) is an agent, so active_agents() ordinarily returns at least one agent.

whenever_active(index)
      returns T if the whenever statement identified by index is active. The index is from last_whenever_executed() or current_whenever() above.

whenever_stmts(agent)
        returns a record identifying the event names, corresponding whenever statements associated with agent, and which of the statements are currently active as a result of activate or deactivate statements. The record has three fields, event, stmt and active, which are string, integer and boolean vectors, respectively. For example,

    a := create_agent()
    whenever a->foo do print 1
    whenever a->bar do print 2
    b := whenever_stmts(a)

assigns to b a record whose event field corresponds to the string vector "foo bar", whose stmt field holds as its first and second elements the indices of the first and second whenever statements, and whose active field holds two T values.

The following, for example, turns off every whenever statement associated with some agent's ``warning'' event:  

    agents := active_agents()

    for ( i in 1:len(agents) )
        {
        a := ref agents[i]
        w := whenever_stmts(a)
        mask := w.event == "warning"
        deactivate w.stmt[mask]
        }