ZStreamMUX Class Reference

Allows one to multiplex independent sessions over a single ZStreamR/ZStreamW pair. More...

List of all members.

Public Types
	errorNone
	The operation succeeded.
	errorAbortLocal
	The operation failed because Abort was called locally.
	errorAbortRemote
	The operation failed because the remote end called Abort.
	errorSendClosed
	Data could not be sent because Close has already been called locally.
	errorReceiveClosed
	The remote end has called Close and all data has been received.
	errorInvalidSession
	The SessionID is either illegal or refers to a non-existent session.
	errorAlreadyListening
	Attempted to listen with a name that is already being listened for.
	errorNotListening
	Attempted to accept or stop listening for a name that was not being listened for.
	errorBadListenName
	The listener name was illegal (currently zero length is the only illegal name).
	errorConnectionDied
	The ZStreamMUX's underlying connection disappeared.
	errorDisposed
	The ZStreamMUX was disposed before the call could complete.
	waitPending
	Used internally.
enum	Error {   errorNone, errorAbortLocal, errorAbortRemote, errorSendClosed,   errorReceiveClosed, errorInvalidSession, errorAlreadyListening, errorNotListening,   errorBadListenName, errorConnectionDied, errorDisposed, waitPending }
Public Member Functions
void	Startup ()
void	Shutdown ()
Error	Close (SessionID iSessionID)
Error	Abort (SessionID iSessionID)
Error	Send (SessionID iSessionID, const void *iSource, size_t iCount, size_t *oCountSent)
Error	Receive (SessionID iSessionID, void *iDest, size_t iCount, size_t *oCountReceived)
Error	CountReceiveable (SessionID iSessionID, size_t &oCountReceivable)

---

Detailed Description

Allows one to multiplex independent sessions over a single ZStreamR/ZStreamW pair.

Note:

ZStreamMUX is based on some of the ideas from the moribund WebMUX protocol.

ZStreamMUX takes a ZStreamR and a ZStreamW and runs a lightweight protocol over them to support multiple independent sessions. The overall interface is similar to that provided by sockets:

• ZStreamMUX::Listen causes the MUX to listen for sessions being opened by the remote side. Note that we use textual names rather than numeric port IDs.
• ZStreamMUX::Accept retrieves a session that's been opened by the other side, or blocks waiting for such an open to happen.
• ZStreamMUX::Open opens a session to the other side, using a name to identify which of several ZStreamMUX::Listen/ZStreamMUXAccept combos might be active.
• ZStreamMUX::Close half-closes an existing session -- after this call no more data can be sent to the other side, although the other side can continue to send data and you can continue to receive it.
• ZStreamMUX::Abort immediately tears down a session in both directions. Pending receives and sends return with errorAbortLocal or errorAbortRemote (as appropriate).

Sessions are identified with a SessionID. ZStreamMUX supports up to 512 outbound sessions, for a total of 1024 sessions at once. SessionIDs themselves are 16 bit unsigned integers where bits 0-8 distinguish one session from another, bit 14 (0x4000) is always set and bit 13 (0x2000) indicates whether the session was initiated locally (by calling ZStreamMUX::Open) or remotely (by calling ZStreamMUX::Accept). So valid SessionIDs range from 0x6000 to 0x61FF (for locally-initiated sessions) and from 0x4000 to 0x41FF (for remotely-initiated sessions). Note that zero is never a valid sessionID.

Wire Protocol Summary

S = Session ID (full, possibly of limited range)
T = Session ID (near/far implied, again possibly with a limited range)
W = Near/Far session 1 == sender's notion of far (receiver's near)
                     0 == receiver's notion of far (sender's near)
L = Length of payload that follows
K = Length minus one of payload that follows
P = Listener ID
C = Credit (usually must be multiplied by some constant)
_ = Not determined

Payload
  11WS SLLL   .....
  11WS S111   KKKK KKKK   .....
  11WS S111   1111 1111   KKKK KKKK   KKKK KKKK .....

  101W SSSS   KKKK KKKK   .....
  101W SSSS   1111 1111   KKKK KKKK   KKKK KKKK .....

  100W SSSS   SSSS SLLL   .....
  100W SSSS   SSSS S111   KKKK KKKK   .....
  100W SSSS   SSSS S111   1111 1111   KKKK KKKK   KKKK KKKK   .....

Payload SYN
  01TT TTPP   PPPK KKKK   .....

Add credit
  0011 WTTT   TTCC CCCC
  0010 WTTT   TTTT TTCC   CCCC CCCC

SYN (restricted range for session and listener)
  0001 1TTT   TTPP PPPP

FIN
  0001 01WS   SSSS SSSS

RST
  0001 00WS   SSSS SSSS

SYN (unrestricted range)
  0000 111T   TTTT TTTT   PPPP PPPP

SYNACK
  0000 110T   TTTT TTTT

Define Listener
  0000 1011   PPPP PPPP   LLLL LLLL   .....
  0000 1010   PPPP PPPP   LLLL LLLL   LLLL LLLL   .....

UNUSED
  0000 100_ = 2 different sequences
  0000 0___ = 8 different sequences
  There are ten unused 8 bit sequences available for future use.

---

Member Enumeration Documentation

enum ZStreamMUX::Error

Enumerator:

errorNone	The operation succeeded.
errorAbortLocal	The operation failed because Abort was called locally.
errorAbortRemote	The operation failed because the remote end called Abort.
errorSendClosed	Data could not be sent because Close has already been called locally.
errorReceiveClosed	The remote end has called Close and all data has been received.
errorInvalidSession	The SessionID is either illegal or refers to a non-existent session.
errorAlreadyListening	Attempted to listen with a name that is already being listened for.
errorNotListening	Attempted to accept or stop listening for a name that was not being listened for.
errorBadListenName	The listener name was illegal (currently zero length is the only illegal name).
errorConnectionDied	The ZStreamMUX's underlying connection disappeared.
errorDisposed	The ZStreamMUX was disposed before the call could complete.
waitPending	Used internally.

---

Member Function Documentation

void ZStreamMUX::Startup

(

)

Establish a multiplex connection using fStreamR and fStreamW to communicate. The ZStreamR and ZStreamW need only support the normal facilities, and will typically be the read/write interfaces of a single ZNetEndpoint (which is of course a ZStreamerRW). However it will likely be advantageous to wrap a ZStreamR_Buffered/ZStreamW_Buffered/ZStreamRW_FlushOnRead combo around raw endpoint streams in order to maxmize the size of read/writes made to the OS.

void ZStreamMUX::Shutdown

(

)

Tear down the multiplexed connection. No exchange of information occurs, we just stop work and dispose working storage. You'll need to use some external technique to ensure that all sessions have finished.

ZStreamMUX::Error ZStreamMUX::Close

(

SessionID

iSessionID

)

Half-close a session.

Parameters:

iSessionID

The session for which we no longer wish to send data. Any call to ZStreamMUX::Send that's already blocked will send all its data. Any subsequent call to Send will fail.

Returns:

• errorNone: All pending sends have completed and will return errorNone. Any future calls to ZStreamMUX::Send will return errorSendClosed.

• errorInvalidSession: The session iSessionID does not exist.

• errorAbortLocal: The session was locally aborted before the half-close could complete.

• errorAbortRemote: The session was remotely aborted before the half-close could complete.

ZStreamMUX::Error ZStreamMUX::Abort

(

SessionID

iSessionID

)

Abort a session.

Parameters:

iSessionID

The session which we want to shoot in the head. Any pending calls to ZStreamMUX::Send, ZStreamMUX::Receive or ZStreamMUX::Close will return with errorAbortLocal. All resources for the session are released.

Returns:

• errorNone: All pending sends and receives have been aborted and will return errorAbortLocal.

• errorInvalidSession: The session iSessionID does not exist.

ZStreamMUX::Error ZStreamMUX::Send	(	SessionID	iSessionID,
		const void *	iSource,
		size_t	iCount,
		size_t *	oCountSent
	)

Send data to the remote side of the session.

Parameters:

	iSessionID	The session over which we wish to send data.
	iSource	A pointer to the data which we wish to send.
	iCount	The number of bytes to send.
	oCountSent	Optional output argument which will be updated with the number of bytes actually sent. If an abort occurs before all data has been sent this will hold the number that was sent prior to the abort.

Returns:

• errorNone: Data was sent, oCountSent holds some value between 0 and iCount (currently we always send everything).

• errorInvalidSession: The session iSessionID does not exist.

• errorSendClosed: ZStreamMUX::Close had previously been called for this session.

• errorAbortLocal, errorAbortRemote: The session was aborted.

ZStreamMUX::Error ZStreamMUX::Receive	(	SessionID	iSessionID,
		void *	iDest,
		size_t	iCount,
		size_t *	oCountReceived
	)

Receive data from the remote side of the session.

Parameters:

	iSessionID	The session from which we wish to receive data.
	iDest	A pointer to where received data should be placed.
	iCount	The maximum number of bytes to receive.
	oCountReceived	Optional output argument which will be updated with the number of bytes actually received.

Returns:

• errorNone: The size_t referred to by oCountReceived holds the number of bytes that were succesfully received. If less than iCount then it's likely (but not certain) that the remote side has closed the session.

• errorInvalidSession: The session iSessionID does not exist.

• errorReceiveClosed: The remote side has called ZStreamMUX::Close, and all data sent prior to that has already been received.

• errorAbortLocal, errorAbortRemote: The session was aborted.

ZStreamMUX::Error ZStreamMUX::CountReceiveable	(	SessionID	iSessionID,
		size_t &	oCountReceivable
	)

Get the number of bytes that can be read without blocking.

Parameters:

	iSessionID	The session from which we wish to receive data.
	oCountReceivable	On success this will hold the number of bytes that could be retrieved by a call to ZStreamMUX::Receive without blocking.

Returns:

• errorNone

• errorInvalidSession: The session iSessionID does not exist.

• errorReceiveClosed: The remote side has called ZStreamMUX::Close, and all data sent prior to that has already been received.

---

The documentation for this class was generated from the following files:

• src/stream/ZStreamMUX.h
• src/stream/ZStreamMUX.cpp

---