| Creating Interreality: The Virtual Object System: Version 0.12.0 | ||
|---|---|---|
| Prev | Chapter 7. VOP, the Virtual Object Protocol | Next |
While all essential VOS operations can be carried out using the simple message protocol above, it has some limitations. Foremost among them is that the round-trip latency between a message and its reply can slow down an operation involving many messages, some of which may depend on information contained in replies to previous messages. Also, the actual time of message excution is not controllable: they are simply received, queued and executed as soon as possible by the remote site.
The Message Blocks extension addresses these issues, and introduces several very powerful features into the VOP. One major use of Blocks is in creating "scripts" which may be human-written, then read off disk by VOS and sent to a remote or local site.
First, a <default> element is added. The attributes to this element define values which are to be used for any attributes omitted on future messages. The attributes which can be used with <default> are to, from and method.
For example:
<default to="vop://foo" />
<message from="vop://bar" method="bing"> ... </message>
<message to="vop://baz" from="vop://bar" method="bang">
... </message>
The "to" attribute has been omitted from the message with method="bing". The <default> element preceding it, however, idicates that to="vop://foo" should be used. The message with method="bang", however, does have a "to" attribute, so the default "to" does not apply.
The <messageblock> element is a container for messages: the messages and other elements within the <messageblock> tags are not executed as they arrive. Instead, they are stored for future execution by the <include> element.
The mesageblock element requires one element, "name", which may be any unique ID. The messageblock element may contain <message> elements, <update> elements, <default> elements, or <include> elements (?) (though it must not include itself).
The include element is similiar to a message, but it triggers a pre-sent messageblock. It requires an attribute "method", which is the ID defined in the name attribute of a pre-sent messageblock. <include> also allows an optional "time" attributes, discussed in "Scheduling", below. <include> may be empty (?) or include tags specifying parameters and their values for the block.
<messageblock> define a context in which parameter substiution is possible. There are two forms of parameter substitution. Parameters may be passed to a messageblock by using the parameter names as fields to <include>:
<include method="blockname">
<key1>value</key1>
<key2>value2</key2>
</include>
Inside the messageblock, the parameter may be used anywhere, by writing $(PARAM), where PARAM is the name of the parameter. For example:
<messageblock name="example">
<default from="vop://harpo" />
<message method="$(meth)" to="$(To)">
<field>$(f)</field>
...
</message>
</messageblock>
<include method="example">
<meth>pow</meth>
<To>vop://groucho</To>
<f>pumpkin</f>
</include>
<include method="example">
<meth>zap</meth>
<f>tomato</f>
<To>vop://chico</To>
</include>
Note:
that the parameter names are case-sensitive
the use of <default>
the compact reusablity that message blocks, includes and parameters allows.
The second form of substitution lets a message in a message block use a field from a reply to a previous message in it's same block. This form uses the syntax $NONCE(FIELD) where NONCE is a unique identifier assigned to a message with a "nonce" attribute. (All messages have nonces, which associate messages and their replies. Usually, they are automatically assigned, but may be explicitly set as well). Any message which uses a reply-field substitution must also declare which message it depends on with a "depends" attribute.
Additionally, both the NONCE and FIELD parts may be replaced by a parameter or another reply reference, and a parameter name may be supplied by another parameter or a reply reference, ad infinitum.
In fact, you must do this if you plan to use a message block more than once, as the nonces in the message in each inclusion of the block must be different to avoid strange and undesirable interactions.
Example:
<messageblock name="example">
<default to="vop://zeppo" from="vop://harpo" />
<message nonce="$(AbraNonce)" method="abracadabra">...</message>
<message depends="$(AbraNonce)" method="shazaam">
<!-- "a" is a field in the reply to "abracadabra": -->
<s>$$(AbraNonce)(a)</s>
<!-- $(field) and $(AbraNonce) are parameters to this block: -->
<field>$$(AbraNonce)($(field))</field>
</message>
</messageblock>
<include method="example">
<AbraNonce>ex_abra_01</AbraNonce>
<field>foo</field>
</include>
<include method="example">
<AbraNonce>ex_abra_02</AbraNonce>
<field>bar</field>
</include>
One more feature is available within message blocks: scheduling. By default, all messages are scheduled to be executed as soon as possible after being received. Or, in the case of message blocks, as soon as the <include> is received. You may wish to delay messages for some amount of time, however. This is done with the "time" attribute, an optional attribute for <message>, <update> and <include>. This time is the delay, in seconds (decimal fractions are okay), from when the message (or include) is received, that it should be executed. (This of course will also delay any reply to that message).
Due to network latency, the exact delay is impossible to determine, but if the network latency remains consistent, then the delays will remain mostly consistent.
For an example "script" containing message blocks, see the playlistd application, in the "jukebox" package. playlistd uses a series of message blocks, read from a file, to define the playback handlers for various file types.