Class: TCaucusMember

Declaration: Caucus.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TStandardCaucusMember

Purpose:

TCaucusMember is an abstract base class that defines the interface between a caucus member and a caucus. A member joins a caucus by creating an instance of a class derived from TCaucusMember. There is one TCaucusMember instance per member, and one member per TCaucusMember instance. When a thread joins a caucus by creating a TCaucusMember, it receives an identity that is unique for the duration of the TCaucusMember. This identity can be used to keep track of the activities of the different members. If a thread leaves, and then rejoins a caucus, it receives a new identity. Hence, it is a new member as far as the caucus is concerned. The GetIdentity call returns the identity of the TCaucusMember. This is an integer of type Identifier. Other caucus member facts: (1) Each active member of a caucus has a different CacucusMember identity. (2) A member's identifier value can be reused after a member has left the caucus. (3) Different caucuses can have active members with the same identifier value. (4) Clients of TCaucusMember typically use Identifier as the key to store client-specific information. CaucusMembers can be wrapped up in TCollectibleLongs to be used in collection classes. The TCaucusSendMessage class and its derived class, TStandardCaucusSendMessage, are used to send messages to a caucus. Messages are atomic in nature, and not a continuous data stream. The message is sent to all caucus members, including the sender. The sending TCaucusMember can filter out local messages by comparing the message sender's identity to the TCaucusMember's own identity. The TCaucusReceiveMessage class and its derived class, TStandardCaucusReceiveMessage, are used to receive a message from the caucus. The specific implementation of the Caucus Framework, TStandardCaucusMember, allows a member to pause and resume messages sent to the caucus. Pausing means any messages sent after the pause message is queued internally. Only after a resume are the pending messages released. Pausing allows a member to synchronize shared data among members. To pause the Caucus, send a TStandardCaucusPauseMessage. A member sending a pause message knows all messages have been received when that member receives its own pause message. To resume the caucus, send a TStandardCaucusResumeMessage. Only the member who sent the original pause message can resume. Pause and Resume might not be possible with other implementations of the Caucus Framework.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Derived classes must override the pure virtual functions Leave, GetIdentity, StartSend, EndSend, StartReceive, and EndReceive. TStandardCaucusMember derives from CaucusMember, which implements the caucus protocol using the message streams interface.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TCaucusMember::~TCaucusMember

virtual ~ TCaucusMember ()

Interface Category:

API.

Purpose:

Destructor. When a TCaucusMember instance is deleted, its Leave member function must be called by the most derived destructor. (This is a derived class responsibility.)

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TCaucusMember::Leave

virtual void Leave ()

Interface Category:

API.

Purpose:

Leaves the caucus of which this object is a member. Caucus members leave the caucus by calling Leave. All caucus members including the sending member receive a Leave message. When Leave is called, all threads blocked waiting for that TCaucusMember instanceÕs StartReceive member function will unblock and receive TCaucusException::kNotInCaucus exceptions. When a TCaucusMember instance is deleted, its Leave member function must be called by the most derived destructor. (This is a derived class responsibility.) If Leave is called more than once, the additional calls have no effect. If a caucus member crashes, then eventually the caucus implementation will notice this fact, and at that time, the other caucus members receive a Leave message. The amount of time this takes depends upon the implementation. Once a member has left the Caucus, all subsequent calls to send or receive a message cause an exception of type TCaucusException::kNotInCaucus.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Member Function: TCaucusMember::GetIdentity

virtual TCaucusMember :: Identifier GetIdentity () const

Interface Category:

API.

Purpose:

Returns the unique Caucus member identifier. It's only valid when the member has joined a Caucus. When a thread joins a caucus by creating a derived class of TCaucusMember, it receives an identity that is unique for the duration of the member. This identity can be used to keep track of the activities of the different members. If a thread leaves, and then rejoins a caucus, it receives a new identity. Hence, it is a new member as far as the caucus is concerned. The GetIdentity call returns the identity of the member. This is an integer of type Identifier.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns member identity of type TCaucusMember::Identifier.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Member Function: TCaucusMember::TCaucusMember

TCaucusMember ()
TCaucusMember (const TCaucusMember & other)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TCaucusMember & other -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TCaucusMember is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TCaucusMember::operator=

TCaucusMember & operator =(const TCaucusMember & other)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TCaucusMember & other -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TCaucusMember is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TCaucusMember::StartSend

virtual TStream * StartSend ()

Interface Category:

API.

Purpose:

Initiates a message send operation. This function returns the stream used to send the message.

Calling Context:

Called by a send message object. Clients send messages to the caucus via TCaucusSendMessage. TCaucusSendMessage's stream conversion operator returns this cached stream for clients to stream data into.

Parameters:

Takes no parameters.

Return Value:

Returns the stream used to send the message.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Member Function: TCaucusMember::EndSend

virtual void EndSend (TStream * streamFromStartSend)

Interface Category:

API.

Purpose:

Terminates a message send operation. The input parameter is the stream returned from a call to StartSend, and is the message to be terminated. This function should clean up the stream.

Calling Context:

Called by a send message object.

Parameters:

TStream * streamFromStartSend -The stream returned from a call to StartSend.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Member Function: TCaucusMember::StartReceive

virtual TStream * StartReceive ()
virtual TStream * StartReceive (TCaucusMember :: Identifier & sender)
virtual TStream * StartReceive (TCaucusMember :: Identifier & sender, bool & isLeaveMessage)

Interface Category:

API.

Purpose:

Initiates a message received operation. This function returns the stream to be used to receive the message.
Initiates a message received operation. This function returns the stream to be used to receive the message. The identifier is set to the sender's member identifier.
Initiates a message received operation. This function returns the stream to be used to receive the message. The identifier is set to the sender's member identifier. The Boolean flag is set to true if the message is a leave message. Leave message has zero bytes of data.

Calling Context:

Parameters:

Takes no parameters.
TCaucusMember :: Identifier & sender -The sender of the message.
TCaucusMember :: Identifier & sender -The sender of the message
bool & isLeaveMessage -A flag indicating whether the message is a leave message. If the flag is true, the stream returned will have zero bytes of data.

Return Value:

Returns the stream to be used to receive the message.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Member Function: TCaucusMember::EndReceive

virtual void EndReceive (TStream * streamFromStartReceive)

Interface Category:

API.

Purpose:

Terminates a message receive operation. The input parameter is the stream returned from a call to StartReceive, and is the message to be terminated. This function should clean up the stream.

Calling Context:

Called by TCaucusReceiveMessage.

Parameters:

TStream * streamFromStartReceive -The stream returned from a call to StartReceive.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TCaucusMember.

Click the icon to mail questions or corrections about this material to Taligent personnel.