[Bugs & Requests][Wiki]

6.4. Messaging Primitives

VOP messages are basically asynchronous. In particular, when a local Vobject is modified, it sends an asynchronous update message to update the cached state of all its stubs. However, in many cases more complex forms of interaction are required. For example, method invocation on a stub Vobject requires a form of remote procedure call on the corresponding local Vobject. In order to support the various messaging semantics a programmer may need, the VOP messaging layer offers several "messaging primitives", or general forms of interaction:


This is the most basic primitive, which simply sends the message in an asynchronous fashion. This primitive does not cause any blocking of the caller. Any reply messages the recipient may send in response are processed in appropriate callback methods. This primitive is typically used for cache update messages, or internally for implementing the more complex primitives.


This primitive models a remote method call. It sends the message to the remote peer, and blocks the caller. Once a reply message is received, the primitive returns control to the caller, and passes the received message as return value. The received message must be evaluated by the caller, it is never passed to any callbacks. This primitive is typically used for status queries and call/return style interactions.


This primitive is a mix of the first two. Conceptually, it requests cache state updates from the remote peer. For that purpose, the primitive sends the message to the remote peer, and blocks the caller. The recipient then sends one or more reply messages, which are passed to appropriate callbacks for processing. Only after the last reply is received, control is transferred back to the caller. There is no return value. This is typically used for registering change listeners, which must make sure that the requester has a valid cache state before any further interactions are allowed.

In the latter two primitives, protocol errors may occur due to missing parameters, wrong response types, non-existent targets, etc. The peer should indicate these by sending an error message, see below. Such error messages must not be passed to callbacks nor returned to the caller. Instead, the error should be indicated by means of an exceptions, per-thread errno value, or similar mechanisms. It is up to the caller to treat errors as fatal or recoverable.

The primitives above cover outgoing messages only. For incoming messages, the VOP messaging layer uses callbacks. The programmer must associate a callback object with each connection; usually, the associated site Vobject serves this purpose. The messaging layer reads incoming messages in an internal receiving loop, which performs some simple pre-processing. In particular, it detects replies that belong to a pending INVOCATION or REQUEST primitive, as well as any protocol errors, and filters these in an appropriate manner. All remaining unfiltered messages are passed to appropriate callback methods of the delegate object. The chosen callback depends on the type of the received message; see the next section.


For unfiltered messages of type <message>.


For unfiltered messages of type <update>.


For named message blocks.


For unnamed message blocks.