Protocol-Protocol Operations

This section defines the operations that protocols (and sessions) invoke on each other. In general, each of the operations invokes a corresponding operation in the target protocol or session. For example, an xOpen call will result in the invocation of a protocol specific open routine, e.g. udp_open. For each operation, we give the interface to both the generic x-kernel operation and an example protocol-specific procedure that implements the generic operation. Although nearly the same, the specification for the generic operation and the specification for the protocol-specific routine typically differ in that a self pointer is passed to the protocol-specific routine.

xOpen

The xOpen function is used by high-level protocol hlpRcv to actively open a session associated with low-level protocol llp on behalf of high-level protocol hlpType. Typically, hlpRcv and hlpType refer to the same protocol (see section 2.5.2.) The participants argument is a list of addresses for each participant in the communication. For this, and all calls returning type XObj, a return value of ERR_XOBJ indicates failure, and this must be checked by all callers before using the return value.

Caveat: the high-level protocol will use its self object as the first argument in xOpen, and the lower-level protocol object as the third argument. The lower-level's open routine will see its own self object as the first argument, and the high-level protocols as the second and third arguments. This reversal of argument order preserves the convention that the current protocol's self object is the first argument in the list.

Generic: XObj xOpen(XObj hlpRcv, XObj hlpType, XObj llp, Part * participants)

Specific: XObj udp_open(XObj self, XObj hlpRcv, XObj hlpType, Part * participants)

xOpenEnable

Used by high-level protocol hlpRcv to passively open a session associated with low-level protocol llp on behalf of high-level protocol hlpType. As with xOpen, hlpRcv and hlpType usually refer to the same protocol. A passive open indicates a willingness to accept connections initiated by remote participants. A session is not actually returned, but the low-level protocol, by convention, ``remembers'' this enabling, and later calls the high-level protocol's xOpenDone operation to complete the passive open. participants is an ordered list of addresses for each participant for which the communication has been enabled. In most cases, it contains only a single element: the address of the local participant. A return value of XK_FAILURE indicates failure.

The lower-level protocol generally ``remembers'' an invocation of its xOpenEnable operation by binding an Enable object to the participant information using mapBind.

Generic: xkern_return_t xOpenEnable ( XObj hlpRcv, XObj hlpType, XObj llp, Part * p )

Specific: xkern_return_t udp_openenable ( XObj self, XObj hlpRcv, XObj hlpType, Part * p)

xOpenDisable

Used by high-level protocol hlpRcv to undo the effects of an earlier invocation of xOpenEnable. The contents of the participant argument, hlpRcv and hlpType must be the same as the ones given to xOpenEnable.

Generic: xkern_return_t xOpenDisable( XObj hlpRcv, XObj hlpType, XObj llp, Part* p)

Specific: xkern_return_t udp_opendisable( XObj self, XObj hlpRcv, XObj hlpType, Part* p)

xOpenDisableAll

Used by high-level protocol hlpRcv to inform low-level protocol llp that all previous openEnables made by hlpRcv should be removed.

Generic: xkern_return_t xOpenDisableAll ( XObj hlpRcv, XObj llp )

Specific: xkern_return_t udp_opendisableall ( XObj self, XObj hlpRcv )

xOpenDone

Used by low-level protocol to inform a high-level protocol (hlpRcv) that a session (s) has now been created corresponding to an earlier xOpenEnable on behalf of hlpType. The ``up'' pointer of the session is set to the hlpRcv protocol. This is useful for virtual protocols; this operation can create a path that bypasses the virtual protocol.

3.1 compatibility note: This is like 3.1's x_callopendonewithout participants or hlp; the original x_opendoneno longer exists.

xPush

xCall

Similar to xPush except that a ``reply'' message may be returned through the argument reply_msg. Used with synchronous (RPC-like) protocols. Because the lower protocol typically retains no state for the request message after xCall returns, a message handle is not returned. The message structure for the reply must be initialized; see msgConstructEmpty.

Generic: xkern_return_t xCall (XObj s, Msg * msg, Msg * reply_msg)

Specific: xkern_return_t udp_call (XObj s, Msg * msg, Msg * reply_msg)

xPop

Used by a protocol to pass an incoming message msg up to session s for processing, and to indicate the lower-level session from which the message was received (lls). This calls the pop routine of the session s and increments the session reference count (see section 11). This call is invoked by a protocol on one of its own sessions.

The hdr argument is passed through the infrastructure directly to the protocol-specific routine. It is typically used to pass the header (which the demux routine used to find the session) to the session's pop routine.

Generic: xkern_return_t xPop (XObj s, XObj lls, Msg * msg, void * hdr)

Specific: xkern_return_t udp_pop (XObj self, XObj lls, Msg * msg, void * hdr)

xCallPop

When a synchronous (RPC-like) protocol will be demuxing a message to an asynchronous protocol, xCallPop can be used to allow the upper protocol to return a message. This reply message may be the same one passed to the synchronous protocol via xCallDemux.

Generic: xkern_return_t xCallPop (XObj s, XObj lls, Msg * msg, void * hdr, Msg * rmsg)

Specific: xkern_return_t udp_callpop (XObj self, XObj lls, Msg * msg, void * hdr, Msg * rmsg)

xCloseDone

Used by a low-level protocol to inform the high-level protocol that originally opened session s that the session has been closed by a peer participant.

Generic:xkern_return_t xCloseDone (XObj s)

Specific: xkern_return_t udp_closedone (XObj s)

xClose

Decrements the reference count of an XObj (see section 11), calling the object's close function only if the reference count is zero. This call applies to XObjs that represent both protocols and sessions, but the implications of invoking xClose on a protocol are not fully determined at this time.

3.1 compatibility note: Replaces xCloseProtl and xCloseSession. Note that in 3.1, the XObj's close function was called every time xCloseProtl or xCloseSession was called.

Generic: xkern_return_t xClose (XObj object)

Specific: xkern_return_t udp_close (XObj object)

xControl

Used by one XObj to act upon another XObj for retrieving information or for setting processing parameters. The operation code opcode identifies the action; buf is a character buffer from which an argument is retrieved and/or into which a result is placed; and len is the length of the buffer. The value returned is the length of the valid data in the buffer; the value -1 is used to indicate failure.

There are two ``classes'' of operations: standard ones that may be implemented by more than one protocol, and protocol-specific ones. A full discussion of control operation codes is in section 10.

3.1 compatibility note: The routines controlprotl and controlsessn no longer exist.

Generic: int xControl (XObj object, int opcode, char * buf, int len)

Specific: int udp_control (XObj self, int opcode, char * buf, int len)

xDemux

Used by low-level session s to pass message msg to the high-level protocol that created it. The higher-level protocol is determined from the session object. The higher-level protocol demux routine should find the appropriate session, creating it if necessary, and xPop the message to the session. See 2.3.1 for guidelines on when session creation is appropriate.

The called routine is presented with its protocol object, the session object from the lower-level protocol, and the message.

Generic: xkern_return_t xDemux (XObj s, Msg * msg)

Specific: xkern_return_t udp_demux (XObj self, XObj lls, Msg * msg)

xCallDemux

This call is like xDemux but allows an argument to contain a return message. Used with synchronous (RPC-like) protocols.

Generic: xkern_return_t xCallDemux (XObj s, Msg * msg, Msg * rmsg)

Specific: xkern_return_t udp_calldemux (XObj self, XObj lls, Msg * msg, Msg * rmsg)

xDuplicate

Increments the reference count of session s. This can be used to create a permanent handle on the XObj from a temporary handle, or to create a new equivalent handle from an existing handle. For a full discussion of session reference counts, see section 11.

Generic: xkern_return_t xDuplicate (XObj s)

Specific: xkern_return_t udp_duplicate (XObj self)

xShutDown

Called once for each protocol object to indicate imminent death of the x-kernel. A protocol may choose to take actions to shut down in a graceful manner. In particular, boundary protocols may choose to sever their connections to the outside world in an orderly manner on receipt of this call.

Protocols should generally not invoke this operation on other protocols or on themselves. It is typically invoked by the x-kernel infrastructure itself.

Generic: xkern_return_t xShutDown (XObj protl )

Specific: xkern_return_t udp_shutdown (XObj self)