Last Updated on December 28, 2005 6:50 PM.
Each mote has its own independent tuple space. Agilla provides 6 instructions for accessing the local tuple space. They are listed below with their parameters in parenthesis:
out(Tuple t): insert a tupleinp(Template t): non-blocking removerdp(Template t): non-blocking copyin(Template t): blocking removerd(Template t): blocking copytcount(Template t): count the number of tuples that match
a particular templateregrxn(Reaction r): register a reactionderegrxn(Reaction
r): de-register a reactionAgilla agents use a stack architecture. Tuples and templates are created by pushing their fields onto the stack, followed by the number of fields. The order of the fields on the stack represents the order that they appear in the tuple. For example, the code for inserting tuple <int:1, int:2, string:"abc", loc:(1,1)> and insert it into the local tuple space is:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/out_example.ma
pushloc 1 1 pushn abc pushc 2 pushc 1 pushc 4 // 4 fields in the tuple out // insert tuple halt
Note that since the stack is LIFO, the last field of the
tuple is pushed first. The tuple space provides hard state.
Tuples inserted in the tuple space remain there indefinitely even
if the agent that inserted it no longer exists. Tuples are moved
using instructions in and inp.
The maximum number of fields a tuple can have is limited by the
maximum size of the tuple, which is by default 18 bytes as defined
by AGILLA_MAX_TUPLE_SIZE within $WUAPPS/Agilla/types/TupleSpace.h.
This value
was chosen to ensure
a tuple can fit within a single TinyOS message. The size
of a tuple or template's field is the size of the variable within
the
field
+
1. Variables sizes are given here.
The extra byte within every field is used to indicate the variable
type. In addition, the tuple contains a byte for flags (e.g., whether
the tuple was inserted by the middleware, or by an agent), and a
byte to indicate the number of fields. Thus, the total size of a
tuple is the sum of its fields plus 2. For example, the tuple in
the example above would contains 3+3+3+5+2=14 bytes.
The middleware automatically inserts a HostID tuple containing <"hid", value>, and an AgentID tuple consisting of <"aid", value>. The value within the HostID tuple is the address of the local host. The value within an AgentID tuple is the unique ID of an agent. Both the HostID and AgentID tuples are 8 bytes (string = 3, value = 3, header = 2).
To retrieve a tuple from the local tuple space, you need to supply a template that matches the tuple. A template is the same as a tuple except some of its fields may wild cards that match by type. A match occurs when the template and tuple have the same number of fields, and each field within the tuple matches that of a template. If the template's field is a not a wild card, the tuple's field must match exactly. This form of matching is called "match by value." However, if the template's field is a wild-card variable, then the tuple's field must simply be of the same type. This form of matching is called "match by type." Note that a type-variable may match "ANY" other type, in which case a match always occurs. The template may contain any mix of match-by-value and match-by-type fields. For example, the following agent pushes a template that is exactly the same as the tuple; it matches every field by value:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/inp_example.ma
pushloc 1 1 pushn abc pushc 2 pushc 1 pushc 4 // 4 fields in template inp // remove tuple rjumpc FOUND // jump to FOUND if success pushc 1 putled // turn on red LED if not found halt FOUND pushc 2 putled // turn on green LED if found halt
If
this agent executes on the same node that the out_example.ma agent
ran on, the green LED will light up.
The following agent uses a template that matches every field by value:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/inp_type_example.ma
pusht LOCATION pusht STRING pusht VALUE pusht VALUE pushc 4 // 4 fields in template inp rjumpc FOUND pushc 1 putled // turn on red LED if not found halt FOUND pushc 2 putled // turn on green LED if found halt
The following template matches some fields by value and others by type:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/inp_mix_example.ma
pushloc 1 1 // match by value pusht STRING // match by type pushc 2 // match by value pusht VALUE // match by type pushc 4 // 4 fields in template inp rjumpc FOUND pushc 1 putled // turn on red LED if not found halt FOUND pushc 2 putled // turn on green LED if found halt
The following template does NOT match the tuple since it's first field, <int:0>, does not match:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/inp_fail_example.ma
pushloc 1 1 pushn abc pushc 2 pushc 0 // this should NOT match! pushc 4 // 4 fields in template inp rjumpc FOUND pushc 1 putled // turn on red LED if not found halt FOUND pushc 2 putled // turn on green LED if found halt
If the above agent is injected, the red LED should turn on.
An agent can also register reactions. A reaction allows an agent to respond to the presence of a tuple in the local tuple space. It is used to prevent the agent from having to poll for a tuple, which is inefficient. Reactions consist of a template, address, and a block of code. The template specifies when the reaction should fire. When a reaction fires, the agent's current PC and the matching tuple are pushed onto the stack. The agent's program counter is then changed to the reaction's address, which points to the first instruction in the reaction's code. The reaction's code is called the reaction's "callback function".
A reaction's callback function has the following structure:
BEGINRXN ... ... ... endrxn
The first instruction should be labeled so its address can be
pushed onto the stack when registering the reaction. In this case, the label
is "BEGINRXN". A label can be any arbitrary string with no spaces.
The last instruction must be endrxn,
which tells
Agilla when the agent finishes executing the callback function. To
prevent race conditions, a reaction's callback function is non-preemptable.
If there
are
multiple tuples matching the reaction's
template, or if there are multiple reactions belonging to the same agent that
are all enabled (i.e., can fire), all of the reactions will eventually fire,
one at a time. If a matching tuple appears in the midst of another reaction,
the reaction sensitive to the tuple will only be fired after the current reaction
is finished. endrxn expects
there to be a value on top of the stack. This value is the address of
the next instruction to
execute
after
finishing
executing a callback function. endrxn changes
the program counter to be this value. By default, Agilla pushes the address
of the instruction that the agent was executing before the reaction fired onto
the stack. This address may be used by endrxn to resume the agent
running where it left off prior to handling a reaction.
Agilla reactions are asynchronous and weak. They are asynchronous in that a matching tuple may be inserted and removed into the local tuple space without the reaction ever getting a chance to fire. They are weak in that when a matching tuple is placed in the tuple space, the reaction may not immediately fire. However, if the matching tuple remains, the reaction is guaranteed to eventually fire. This is in contrast to a strong reaction, which is guaranteed to fire at the first chance possible (i.e., when the agent is not already executing another reaction's callback function, and is not blocked on another operation).
A reaction is designed to be executed quickly and atomically.
It is analogous to a TinyOS event. An agent cannot execute blocking operations
like in, rd, wait,
or sleep while executing a reaction's call-back
function.
To register a reaction, the agent pushes a template and an address onto the stack. It then calls regrxn. For example, consider the following agent:
$WUAPPS/AgillaAgents/Tutorials/Lesson4/regrxn_example.ma