SPECIFICATION
SYNOPSIS
JOIN merges up to N outgoing messages pushed to N different sessions into a single outgoing message. When this message arrives it its broken up into its original configuration and demuxed to N potentially different protocols. JOIN is bidirectional and will perform the same action on the reply. N can be any number between 1 and 16. The default value for N is four and other values may be set using ROM file options.

The number of xOpen's and xOpenenable's that should be performed on JOIN and the number of xOpenDone's JOIN will perform on higher level protocols should be equal to N + 1. The first open will return, and the first open done will produce, a control session which is not used to transmit data. To transmit a message, the user of JOIN should push a single message to one or more of the remaining N sessions and then invoke the JOINDONE control operation on the control session. When JOINDONE is invoked on JOIN, the protocol gathers all of the packets pushed, joins them into a single packet, and transmits it.

When the packet arrives at the receiver it is broken up into its original configuration and demuxed to the appropriate higher level protocols. If no packet has been pushed to a specific JOIN session, no packet will be demuxed at the corresponding join session at the receiver. When this is finished JOIN will perform an upward JOINDONE control operation on the session or protocol passed to JOIN by the receiving protocol using the JOINSETCONTROL operation. This allows the user to detect if any of the incoming message fragments have been lost or never sent. NOTE: some protocol must know that it is using JOIN and must perform JOINSETCONTROL immediately after the first openDone performed by JOIN on the SESSION passed up by the openDone.

The order in which JOIN will demux the messages to the higher level protocol(s) can be set in the ROM file.

REALM
JOIN is in the ASYNC realm.

PARTICIPANTS
JOIN takes arbitrary participants. The only restriction is that JOIN must be opened N+1 times with each open having exactly the same participant list. The best way to achieve these duplicate opens is for the higher level protocol to perform one open which eventually trickles down to JOIN and then do a get participants on the resulting session. This participant list should be used to perform the remaining opens. JOIN will create one and only one set of JOIN sessions for each unique address. Attempts to open another set of JOIN sessions with the same address will fail. Note there is a potential race condition if the higher level protocol which knows about join is in a different scheduling domain from JOIN.

CONTROL OPERATIONS
JOINGETNUMSEG: Returns N.

JOINGETORDER: Returns an array of 16 integers which gives the order in which JOIN will demux the messages fragments. While all 16 ints are returned, only the first N of them should be considered valid. If N=4, then ``0 1 2 3 4'' is a valid order and ``4 3 2 1'' is also a valid order.

JOINDONE: When invoked on the JOIN control session it causes JOIN to collect all fragments currently available and send a composite message. JOIN invokes JOINDONE on the higher level protocol or session passed to it by JOINSETCONTROL when it is finished demultiplexing message fragments. JOINDONE takes no arguments.

JOINSETCONTROL: Takes a protocol or session as argument. Some higher level protocol must invoke this operation on the JOIN control session before any packets are delivered. The protocol implementor must implement a JOINDONE control operation in the control procedure.

CONFIGURATION
The composability of JOIN is rather complex and not particularly well understood. There must be some higher level protocol that knows it is being composed over JOIN. This protocol will be configured over N+1 protocols. The first protocol must be JOIN. Between this protocol JOIN any number of other protocols may be composed on each of the remaining N paths. For example the following is a valid join protocol graph:

name=auth protocols= join, join,join,crypt/one,join,crypt/two;
name=crypt/one protocols=join;
name=crypt/two protocols=join;
name=join ....

Note that the participant lists that propagate to JOIN through each of these paths must be identical. Therefore if one path to JOIN modifies the participant list, all other paths must also perform identical modifications. For situations where the incoming and outgoing paths differ, it may be possible to use standard asymmetric protocol graph techniques to allow the incoming and outgoing message to pass through different protocol graphs. Note that any protocol composed between AUTH and JOIN must xPush no more than one message down for each xPush done to it. Protocols which fragment messages should not be composed between AUTH and JOIN.

ROM File
The ROM file is used to set N and the order in which the message parts should be demuxed to higher level protocols. The following is an example ROM file:

join segments 4
join order 3 2 1 0

After the user has set the number of segments to be joined, he should set the order at which he would like the message segments to be demuxed. In this case JOIN will demux the messages in reverse order. Note the default N is 4 and the default order is (0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15). However the user should always set N and the order.

AUTHOR
Sean W. O'Malley