This section defines the operations that protocols and sessions invoke on each other. In general, each of these 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.
The xOpen function is used by high-level protocol hlp to actively open a session associated with low-level protocol llp on behalf of high-level protocol hlpType. Typically, hlp 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 Protl or Sessn, a return value of ERR_PROTL or ERR_SESSN, respectively, indicates failure. This must be checked by all callers before using the return value.
Note that the high-level protocol will use its self object as the first (and usually second) argument in xOpen, and the lower-level protocol object as the third argument. The lower-level protocol'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 of the protocol-specific function.
Generic: Sessn xOpen(Protl hlp, Protl hlpType, Protl llp, Part *participants)
Specific: Sessn udp_open(Protl self, Protl hlp, Protl hlpType, Part *participants)
Used by high-level protocol hlp to passively open a session associated with low-level protocol llp on behalf of high-level protocol hlpType. As with xOpen, hlp 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. The participants argument is an ordered list of addresses of 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: XkReturn xOpenEnable(Protl hlp, Protl hlpType, Protl llp, Part *participants)
Specific: XkReturn udp_openenable(Protl self, Protl hlp, Protl hlpType, Part *participants)
Used by high-level protocol hlp to undo the effects of an earlier invocation of xOpenEnable. The hlp and hlpType arguments and the contents of the participants argument must be the same as the ones given to xOpenEnable.
Generic: XkReturn xOpenDisable(Protl hlp, Protl hlpType, Protl llp, Part *participants)
Specific: XkReturn udp_opendisable(Protl self, Protl hlp, Protl hlpType, Part *participants)
Used by high-level protocol hlp to inform low-level protocol llp that all previous openEnables made by hlp should be removed.
Generic: XkReturn xOpenDisableAll(Protl hlp, Protl llp)
Specific: XkReturn udp_opendisableall(Protl self, Protl hlp)
Used by low-level protocol to inform a high-level protocol (hlp) that a session (session) has now been created corresponding to an earlier xOpenEnable on behalf of hlpType.
Note that the hlpType argument is not required in the generic call because that value was saved in the Sessn object at the time of the xOpenEnable call.
Generic: XkReturn xOpenDone(Protl hlp, Protl llp, Sessn session)
Specific: XkReturn udp_opendone(Protl self, Protl llp, Sessn session, Protl hlpType)
Used by a low-level protocol to inform the high-level protocol that the session it originally opened has been closed by a peer participant.
Generic: XkReturn xCloseDone(Sessn session)
Specific: XkReturn udp_closedone(Sessn self)
Used by low-level session lls to pass message message to the high-level protocol that created it. The high-level protocol demux routine should find the appropriate session, creating it if necessary, and xPop the message to the session. See Section 2.3.2 for guidelines on when session creation is appropriate.
Generic: XkReturn xDemux(Protl hlp, Sessn lls, Msg *message)
Specific: XkReturn udp_demux(Protl self, Sessn lls, Msg *message)
This call is like xDemux but provides an argument to contain a return message. Used with synchronous (RPC-like) protocols.
Generic: XkReturn xCallDemux(Protl hlp, Sessn lls, Msg *request, Msg *reply)
Specific: XkReturn udp_calldemux(Protl self, Sessn lls, Msg *request, Msg *reply)
Used by one protocol to act upon another protcol (llp) for retrieving information or for setting processing parameters. The operation code opcode identifies the action; buffer is a character buffer from which an argument is retrieved and/or into which a result is placed; and length is the length of the buffer. Returns an integer that indicates the length in bytes of the information which was written into the buffer, or -1 to indicate an error. 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 11.
Generic: int xControlProtl(Protl llp, int opcode, char *buffer, int length)
Specific: int udp_controlprotl(Protl self, int opcode, char *buffer, intlength)
Decrements the reference count of a Sessn, calling the session's close function only if the reference count is zero.
Generic: XkReturn xClose(Sessn session)
Specific: XkReturn udp_close(Sessn self)
Used by a protocol to pass an incoming message up to session hls for processing, and to indicate the lower-level session from which the message was received (lls). This calls the pop routine of the session hls and increments the session reference count. This call is invoked by a protocol on one of its own sessions.
The hdr argument is passed 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: XkReturn xPop(Sessn hls, Sessn lls, Msg *message, void *hdr)
Specific: XkReturn udp_pop(Sessn self, Sessn lls, Msg *message, void *hdr)
When a synchronous (RPC-like) protocol is 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: XkReturn xCallPop(Sessn hls, Sessn lls, Msg *request, void *hdr, Msg *reply)
Specific: XkReturn udp_callpop(Sessn self, Sessn lls, Msg *request, void *hdr, Msg *reply)
Used by a high-level protocol that opened session lls to pass a message down through that session. The return value is an opaque handle on the message that was sent. This handle may be used to identify this message in subsequent xControlProtl and xControlSessn operations. The message handle may also take one of three special values: a return value of XMSG_NULL_HANDLE indicates a successful push to a protocol which does not generate handles, XMSG_ERR_HANDLE indicates general failure, and XMSG_ERR_WOULDBLOCK indicates that a session in non-blocking mode would normally have blocked the push.
Generic: XkHandle xPush(Sessn lls, Msg *message)
Specific: XkHandle udp_push(Sessn self, Msg *message)
Similar to xPush except that a reply message may be returned through the argument reply. 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 Section 3.2.1).
Generic: XkReturn xCall(Sessn lls, Msg *request, Msg *reply)
Specific: XkReturn udp_call(Sessn self, Msg *request, Msg *reply)
Used by one session to act upon another session (lls) for retrieving information or for setting processing parameters. The operation code opcode identifies the action; buffer is a character buffer from which an argument is retrieved and/or into which a result is placed; and length is the length of the buffer. Returns an integer that indicates the length in bytes of the information which was written into the buffer, or -1 to indicate an error. There are two ``classes'' of operations: standard ones that may be implemented by sessions of more than one protocol, and protocol-specific ones. A full discussion of control operation codes is in Section 11.
Generic: int xControlSessn(Sessn lls, int opcode, char *buffer, int length)
Specific: int udp_controlsessn(Sessn self, int opcode, char *buffer, int length)
Used by one session to retrieve the participant list of another session, lls.
Generic: Part *xGetParticipants(Sessn lls)
Specific: Part *udp_getparticipants(Sessn self)
Increments the reference count of session. This can be used to create a permanent handle on session from a temporary handle, or to create a new equivalent handle from an existing handle. For a full discussion of session reference counts, see the x-kernel Tutorial [8].
Generic: XkReturn xDuplicate(Sessn session)
Specific: XkReturn udp_duplicate(Sessn self)