DSSX_Synch
DSSX_Synch
dssx
1998 12-06
CLASS
DSSX_Synch - A DSS extended construct implementing a synchronous communication mechanism
SYNOPSIS
This class provides a synchronous communication mechanism using DSS as a
transport. The model implemented is analogous to clients asking questions
and servers providing answers. The members functions are named accordingly.
There is no direct mapping from clients to servers. Multiple clients and
servers may use the same DSSX_Synch. However, a client will get the answer
corresponding to the question it sent.
The normal order of operations for a complete synchronized communication is as
follows:
| 1. CLIENT CALLS QuestionSend() |
thereby sending the data necessary to communicate with the server.
|
| 2. SERVER CALLS QuestionReceive() |
and does whatever processing necessary to generate an answer.
|
| 3. SERVER CALLS AnswerSend() |
to send the answer data back to the client.
|
| 4. CLIENT CALLS AnswerReceive() |
thereby receiving answer data corresponding to the question sent.
|
DSSX_Synch maintains a state with the following possible values:
| DSSX_SYNCH_STATE_READY |
ready for QuestionSend or QuestionReceive
|
| DSSX_SYNCH_STATE_CLIENT |
between QuestionSend and AnswerReceive
|
| DSSX_SYNCH_STATE_SERVER |
between QuestionReceive and AnswerSend
|
If a process attempts to call a member function inappropriate for the current
state the member function will return without completing its operation.
The initial state is DSSX_SYNCH_STATE_READY.
It is possible to have more than one answer pending while a server (in other
words a server may handle more than one question at a time). If a server
calls QuestionReceive more than once before AnswerSend then
the answers will be sent in the order the questions were recieved (FIFO).
Out of order answers can be sent by making use of GetAnswerID and
SetAnswerID.
PARENTS
CONSTRUCTOR
DSSX_Synch(DSSX_Connection *connection, const GPL_CharPtr &spacename, const GPL_CharPtr &synchname, DSS_ChunkConfig *config)
Construct a DSSX_Synch using connection in space spacename
named name. The config argument is used to configure the
actual DSS chunks that DSSX_Ordered is
implemented with.
CLIENT SIDE MEMBER FUNCTIONS
void QuestionSend(char *buffer, unsigned long length)
Send a 'question' pointed to by buffer of length length
to the server.
The current state must be DSSX_SYNCH_STATE_READY before calling. This function
sets the state to DSSX_SYNCH_STATE_CLIENT.
void QuestionSend(GPL_Message *message)
A GPL_Message variant of QuestionSend().
char *AnswerReceive(unsigned long *length)
Receive an 'answer'. The buffer of the answer is returned and the length
is return in length.
The current state must be DSSX_SYNCH_STATE_CLIENT before calling. This function
sets the state to DSSX_SYNCH_STATE_READY.
This function will block until an answer is available.
long AnswerReceive(GPL_Message *message)
A GPL_Message variant of AnswerReceive().
This function returns TRUE on success and FALSE on failure.
char *AnswerPoll(unsigned long *length)
Receive an 'answer'. The buffer of the answer is returned and the length
is return in length.
The current state must be DSSX_SYNCH_STATE_CLIENT before calling. This function
sets the state to DSSX_SYNCH_STATE_READY.
This function will not block is an answer is not available and will return NULL
if there is no answer available.
long AnswerPoll(GPL_Message *message)
A GPL_Message variant of AnswerPoll().
This function returns TRUE on success and FALSE on failure.
CLIENT SIDE MEMBER FUNCTIONS
char *QuestionReceive(unsigned long *length)
Receive a 'question'. The buffer of the question is returned and the length
is return in length.
The current state must be DSSX_SYNCH_STATE_READY before calling. This function
sets the state to DSSX_SYNCH_STATE_SERVER.
This call has two implementations; a poll based and a wait based. The poll based
is less efficient but is more robust to faulty client access. Which
implementation is used is dependent on the pause setting (see SetPause()).
long QuestionReceive(GPL_Message *message)
A GPL_Message variant of QuestionReceive().
This function returns TRUE on success and FALSE on failure.
void AnswerSend(char *buffer, unsigned long length)
Send an 'answer' pointed to by buffer of length length
back to the client.
The current state must be DSSX_SYNCH_STATE_SERVER before calling. This function
sets the state to DSSX_SYNCH_STATE_READY.
void AnswerSend(GPL_Message *message)
A GPL_Message variant of AnswerSend().
MULTIPLE QUESTION SERVER SUPPORT
unsigned long GetAnswerID()
Get the answer id for the last question received. The current state must be
DSSX_SYNCH_STATE_SERVER before calling.
long SetAnswerID(unsigned long answer_id)
Set the answer id for the next AnswerSend call. The current start must
be DSSX_SYNCH_STATE_SERVER before calling. Return TRUE on success and FALSE on
failure. This function fails if answer_id does not specify a pending
answer.
GPL_List<unsigned long> *GetAnswerIDList()
Get the list of all pending answer ids.
OTHER MEMBER FUNCTIONS
short GetState()
Return the current state.
void Invalidate()
Invalidate the DSS chunks implementing the DSSX_Synch. Any member functions
(except the destructor) called after Invalidate have undefined behavior.
void SetPause(long pause)
Set the pause per loop in milliseconds of the poll
based implementation of QuestionReceive().
If the pause is set less than 0 then the wait based implementation is used.
Otherwise the poll based implementation is used.
The default pause setting is DSSX_SPINPAUSE milliseconds.
long GetPause()
Return the current loop pause setting for QuestionReceive().