muscle::QMessageTransceiverThread Class Reference

This is a Qt-specific subclass of MessageTransceiverThread. More...

#include <QMessageTransceiverThread.h>

Inheritance diagram for muscle::QMessageTransceiverThread:

[legend]List of all members.

Public Types
enum	{ SOCKET_SET_READ = 0, SOCKET_SET_WRITE, SOCKET_SET_EXCEPTION, NUM_SOCKET_SETS }
	Enumeration of the socket sets that are available for blocking on; used in GetOwnerSocketSet() and GetInternalSocketSet() calls. More...
Public Slots
status_t	SendMessageToSessions (const MessageRef &msgRef, const char *optDistPath=NULL)
	This method is the same as the MessageTransceiverThread::SendMessageToSessions(); it's reimplemented here as a pass-through merely so it can be a slot.
virtual void	HandleQueuedIncomingEvents ()
	Parses through the incoming-events queue and emits signals as appropriate.
virtual void	Reset ()
	Overridden to also call Reset() on any QMessageTransceiverHandlers we have registered.
Signals
void	BeginMessageBatch ()
	Emitted when MessageReceived() is about to be emitted one or more times.
void	MessageReceived (const MessageRef &msg, const String &sessionID)
	Emitted when a new Message has been received by one of the sessions being operated by our internal thread.
void	EndMessageBatch ()
	Emitted when we are done emitting MessageReceived, for the time being.
void	SessionAccepted (const String &sessionID, uint32 factoryID)
	Emitted when a new Session object is accepted by one of the factories being operated by our internal thread.
void	SessionAttached (const String &sessionID)
	Emitted when a session object is attached to the internal thread's ReflectServer.
void	SessionConnected (const String &sessionID)
	Emitted when a session object connects to its remote peer (only used by sessions that were created using AddNewConnectSession()).
void	SessionDisconnected (const String &sessionID)
	Emitted when a session object is disconnected from its remote peer.
void	SessionDetached (const String &sessionID)
	Emitted when a session object is removed from the internal thread's ReflectServer.
void	FactoryAttached (uint32 factoryID)
	Emitted when a factory object is attached to the internal thread's ReflectServer.
void	FactoryDetached (uint32 factoryID)
	Emitted when a factory object is removed from the internal thread's ReflectServer.
void	ServerExited ()
	Emitted when the thread's internal ReflectServer object exits.
void	OutputQueuesDrained (const MessageRef &ref)
	Emitted when the output-queues of the sessions specified in a previous call to RequestOutputQueuesDrainedNotification() have drained.
void	InternalThreadEvent (uint32 code, const MessageRef &optMsg, const String &optFromSession, uint32 optFromFactory)
	This signal is called for all events send by the internal thread.
Public Member Functions
	QMessageTransceiverThread (QObject *parent=NULL, const char *name=NULL)
	Constructor.
virtual	~QMessageTransceiverThread ()
	Destructor.
virtual bool	event (QEvent *event)
	Overridden to handle signal events from our internal thread.
const Hashtable< uint32, QMessageTransceiverHandler * >	GetHandlers () const
	Returns a read-only reference to our table of registered QMessageTransceiverHandler objects.
virtual status_t	StartInternalThread ()
	Overridden to do some additional setup, before starting the internal thread.
virtual status_t	AddNewSession (const SocketRef &socket, const ThreadWorkerSessionRef &optSessionRef)
	Adds a new session that will use the given socket for its I/O.
status_t	AddNewSession (const SocketRef &socket)
	Convenience method -- calls the above method with a NULL session reference.
status_t	AddNewSession ()
	Convenience method -- calls the above method with a NULL socket and NULL session reference.
virtual status_t	AddNewConnectSession (const ip_address &targetIPAddress, uint16 port, const ThreadWorkerSessionRef &optSessionRef, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Adds a new session that will connect out to the given IP address and port.
status_t	AddNewConnectSession (const ip_address &targetIPAddress, uint16 port, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Convenience method -- calls the above method with a NULL session reference.
virtual status_t	AddNewConnectSession (const String &targetHostName, uint16 port, const ThreadWorkerSessionRef &optSessionRef, bool expandLocalhost=false, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Adds a new session that will connect out to the given hostname and port.
status_t	AddNewConnectSession (const String &targetHostName, uint16 port, bool expandLocalhost=false, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Convenience method -- calls the above method with a NULL session reference.
virtual status_t	PutAcceptFactory (uint16 port, const ThreadWorkerSessionFactoryRef &optFactoryRef, const ip_address &optInterfaceIP=invalidIP)
	Installs a new ReflectSessionFactory onto the ReflectServer (or replaces an existing one) on the given port.
status_t	PutAcceptFactory (uint16 port)
	Convenience method -- calls the above method with a NULL factory reference.
virtual status_t	RemoveAcceptFactory (uint16 port, const ip_address &optInterfaceIP=invalidIP)
	Removes an existing ReflectSessionFactory from the held ReflectServer.
status_t	SetDefaultDistributionPath (const String &distPath)
	Sets our ThreadSupervisorSession's default distribution path to (optPath).
const String &	GetDefaultDistributionPath () const
	Returns our current default distribution path, or "" if it is unset.
int32	GetNextEventFromInternalThread (uint32 &retEventCode, MessageRef *optRetMsgRef=NULL, String *optFromSession=NULL, uint32 *optFromFactoryID=NULL)
	Call this to get the next event notification message from the internal thread.
status_t	RequestOutputQueuesDrainedNotification (const MessageRef &notificationMsg, const char *optDistPath=NULL, DrainTag *optDrainTag=NULL)
	Requests that the MessageTranceiverThread object send us a MTT_EVENT_OUTPUT_QUEUES_DRAINED event when all the specified outgoing message queues have become empty.
status_t	SetNewInputPolicy (const PolicyRef &pref, const char *optDistPath=NULL)
	Tells the specified worker session(s) to install a new input IOPolicy.
status_t	SetNewOutputPolicy (const PolicyRef &pref, const char *optDistPath=NULL)
	Tells the specified worker session(s) to install a new output IOPolicy.
status_t	SetOutgoingMessageEncoding (int32 encoding, const char *optDistPath=NULL)
	Tells the specified worker session(s) to switch to a different message encoding for the Messages they are sending to the network.
status_t	RemoveSessions (const char *optDistPath=NULL)
	Tells the specified worker session(s) to go away.
bool	IsInternalThreadRunning () const
	Returns true iff the thread is considered to be running.
bool	IsCallerInternalThread () const
	Returns true iff the calling thread is the internal thread, or false if the caller is any other thread.
virtual void	ShutdownInternalThread (bool waitForThread=true)
	Tells the internal thread to quit by sending it a NULL MessageRef, and then optionally waits for it to go away by calling WaitForInternalThreadToExit().
status_t	WaitForInternalThreadToExit ()
	Blocks and won't return until after the internal thread exits.
virtual status_t	SendMessageToInternalThread (const MessageRef &msg)
	Puts the given message into a message queue for the internal thread to pick up, and then calls SignalInternalThread() (if necessary) to signal the internal thread that a new message is ready.
virtual int32	GetNextReplyFromInternalThread (MessageRef &ref, uint64 wakeupTime=0)
	This method attempts to retrieve the next reply message that has been sent back to the main thread by the internal thread (via SendMessageToOwner()).
Queue< MessageRef > *	LockAndReturnMessageQueue ()
	Locks the internal thread's message queue and returns a pointer to it.
status_t	UnlockMessageQueue ()
	Unlocks our internal message queue, so that the internal thread can again pop messages off of it.
Queue< MessageRef > *	LockAndReturnReplyQueue ()
	Locks this Thread's reply queue and returns a pointer to it.
status_t	UnlockReplyQueue ()
	Unlocks the reply message queue, so that the internal thread can again append messages to it.
const SocketRef &	GetOwnerWakeupSocket ()
	Returns the socket that the main thread may select() for read on for wakeup-notification bytes.
Hashtable< SocketRef, bool > &	GetOwnerSocketSet (uint32 socketSet)
	This function returns a reference to one of the three socket-sets that GetNextReplyFromInternalThread() will optionally use to determine whether to return early.
const Hashtable< SocketRef, bool > &	GetOwnerSocketSet (uint32 socketSet) const
	As above, but returns a read-only reference.
Protected Member Functions
virtual void	SignalOwner ()
	Overridden to send a QEvent.
virtual QMessageTransceiverThread *	ObtainThread ()
	Must be implemented to return an available QMessageTransceiverThread object, or return NULL on failure.
virtual status_t	RegisterHandler (QMessageTransceiverThread &thread, QMessageTransceiverHandler *handler, const ThreadWorkerSessionRef &sessionRef)
	Must be implemented to attach (handler) to the specified thread.
virtual void	UnregisterHandler (QMessageTransceiverThread &thread, QMessageTransceiverHandler *handler, bool emitEndMessageBatchIfNecessary)
	Must be implemented to detach (handler) from (thread).
virtual void	InternalThreadEntry ()
	Overridden to begin execution of the ReflectServer's event loop.
virtual ThreadSupervisorSessionRef	CreateSupervisorSession ()
	Creates and returns a new ThreadSupervisorSession to use to do the internal-thread-side handling of the messages this API sends.
virtual ThreadWorkerSessionRef	CreateDefaultWorkerSession ()
	Creates and returns a ThreadWorkerSession object.
virtual ThreadWorkerSessionFactoryRef	CreateDefaultSessionFactory ()
	Creates and returns a ThreadWorkerSessionFactory object.
virtual ReflectServerRef	CreateReflectServer ()
	Creates a new ReflectServer object and returns a reference to it.
virtual status_t	MessageReceivedFromOwner (const MessageRef &msgRef, uint32 numLeft)
	If you are using the default implementation of InternalThreadEntry(), then this method will be called whenever a new MessageRef is received by the internal thread.
status_t	SendMessageToOwner (const MessageRef &replyRef)
	May be called by the internal thread to send a Message back to the owning thread.
virtual int32	WaitForNextMessageFromOwner (MessageRef &ref, uint64 wakeupTime=MUSCLE_TIME_NEVER)
	This method is meant to be called by the internally held thread.
virtual void	SignalInternalThread ()
	Called by SendMessageToThread() whenever there is a need to wake up the internal thread so that it will look at its reply queue.
const SocketRef &	GetInternalThreadWakeupSocket ()
	Returns the socket that the internal thread may select() for read on for wakeup-notification bytes.
status_t	LockSignalling ()
	Locks the lock we use to serialize calls to SignalInternalThread() and SignalOwner().
status_t	UnlockSignalling ()
	Unlocks the lock we use to serialize calls to SignalInternalThread() and SignalOwner().
void	CloseSockets ()
	Closes all of our threading sockets, if they are open.
Hashtable< SocketRef, bool > &	GetInternalSocketSet (uint32 socketSet)
	This function returns a reference to one of the three socket-sets that WaitForNextMessageFromOwner() will optionally use to determine whether to return early.
const Hashtable< SocketRef, bool > &	GetInternalSocketSet (uint32 socketSet) const
	As above, but returns a read-only reference.
Friends
class	QMessageTransceiverHandler
class	QMessageTransceiverThreadPool

---

Detailed Description

This is a Qt-specific subclass of MessageTransceiverThread.

It hooks all the standard MessageTransceiverThread events up to Qt signals, so you can just connect() your QMessageTransceiverThread to the various slots in your application, instead of having to worry about event loops and such. In all other ways it works the same as any MessageTransceiverThread object.

Definition at line 73 of file QMessageTransceiverThread.h.

---

Member Enumeration Documentation

anonymous enum [inherited]

Enumeration of the socket sets that are available for blocking on; used in GetOwnerSocketSet() and GetInternalSocketSet() calls.

Enumerator:

SOCKET_SET_READ	set of sockets to watch for ready-to-read (i.e. incoming data available)
SOCKET_SET_WRITE	set of sockets to watch for ready-to-write (i.e. outgoing buffer space available)
SOCKET_SET_EXCEPTION	set of sockets to watch for exceptional conditions (implementation defined)
NUM_SOCKET_SETS	A guard value.

Definition at line 157 of file Thread.h.

---

Constructor & Destructor Documentation

muscle::QMessageTransceiverThread::QMessageTransceiverThread	(	QObject *	parent = NULL,
		const char *	name = NULL
	)

Constructor.

Parameters:

	parent	Passed on to the QObject constructor
	name	Passed on to the QObject constructor

virtual muscle::QMessageTransceiverThread::~QMessageTransceiverThread

(

)

[virtual]

Destructor.

This constructor will call ShutdownInternalThread() itself, so you don't need to call ShutdownInternalThread() explicitly UNLESS you have subclassed this class and overridden virtual methods that can get called from the internal thread -- in that case you should call ShutdownInternalThread() yourself to avoid potential race conditions between the internal thread and your own destructor method.

---

Member Function Documentation

void muscle::QMessageTransceiverThread::MessageReceived	(	const MessageRef &	msg,
		const String &	sessionID
	)			[signal]

Emitted when a new Message has been received by one of the sessions being operated by our internal thread.

Parameters:

	msg	Reference to the Message that was received.
	sessionID	Session ID string of the session that received the message

void muscle::QMessageTransceiverThread::SessionAccepted	(	const String &	sessionID,
		uint32	factoryID
	)			[signal]

Emitted when a new Session object is accepted by one of the factories being operated by our internal thread.

Parameters:

	sessionID	Session ID string of the newly accepted Session object.
	factoryID	Factory ID of the ReflectSessionFactory that accepted the new session.

void muscle::QMessageTransceiverThread::SessionConnected

(

const String &

sessionID

)

[signal]

Emitted when a session object connects to its remote peer (only used by sessions that were created using AddNewConnectSession()).

Parameters:

sessionID

Session ID string of the newly connected Session object.

void muscle::QMessageTransceiverThread::SessionDisconnected

(

const String &

sessionID

)

[signal]

Emitted when a session object is disconnected from its remote peer.

Parameters:

sessionID

Session ID string of the newly disconnected Session object.

void muscle::QMessageTransceiverThread::SessionDetached

(

const String &

sessionID

)

[signal]

Emitted when a session object is removed from the internal thread's ReflectServer.

Parameters:

sessionID

Session ID string of the newly disconnected Session object.

void muscle::QMessageTransceiverThread::FactoryAttached

(

uint32

factoryID

)

[signal]

Emitted when a factory object is attached to the internal thread's ReflectServer.

Parameters:

factoryID

Factory ID of the ReflectSessionFactory that accepted the new session.

void muscle::QMessageTransceiverThread::FactoryDetached

(

uint32

factoryID

)

[signal]

Emitted when a factory object is removed from the internal thread's ReflectServer.

Parameters:

factoryID

Factory ID of the ReflectSessionFactory that accepted the new session.

void muscle::QMessageTransceiverThread::OutputQueuesDrained

(

const MessageRef &

ref

)

[signal]

Emitted when the output-queues of the sessions specified in a previous call to RequestOutputQueuesDrainedNotification() have drained.

Note that this signal only gets emitted once per call to RequestOutputQueuesDrainedNotification(); it is not emitted spontaneously.

Parameters:

ref

MessageRef that you previously specified in RequestOutputQueuesDrainedNotification().

void muscle::QMessageTransceiverThread::InternalThreadEvent	(	uint32	code,
		const MessageRef &	optMsg,
		const String &	optFromSession,
		uint32	optFromFactory
	)			[signal]

This signal is called for all events send by the internal thread.

You can use this to catch custom events that don't have their own signal defined above, or if you want to receive all thread events via a single slot.

Parameters:

	code	the MTT_EVENT_* code of the new event.
	optMsg	If a Message is relevant, this will contain it; else it's a NULL reference.
	optFromSession	If a session ID is relevant, this is the session ID; else it will be "".
	optFromFactory	If a factory is relevant, this will be the factory's ID number; else it will be zero.

status_t muscle::QMessageTransceiverThread::SendMessageToSessions	(	const MessageRef &	msgRef,
		const char *	optDistPath = NULL
	)			[virtual, slot]

This method is the same as the MessageTransceiverThread::SendMessageToSessions(); it's reimplemented here as a pass-through merely so it can be a slot.

Enqueues the given message for output by one or more of our attached sessions.

Parameters:

	msgRef	a reference to the Message to send out.
	optDistPath	if non-NULL, then only sessions that contain at least one node that matches this path will receive the Message. Otherwise all sessions will receive the Message.

Returns:

B_NO_ERROR on success, B_ERROR if out of memory.

Reimplemented from MessageTransceiverThread.

virtual void muscle::QMessageTransceiverThread::HandleQueuedIncomingEvents

(

)

[virtual, slot]

Parses through the incoming-events queue and emits signals as appropriate.

Typically this method is called when appropriate by the event() method, so you don't need to call it yourself unless you are handling event notification in some custom fashion.

virtual status_t muscle::QMessageTransceiverThread::RegisterHandler	(	QMessageTransceiverThread &	thread,
		QMessageTransceiverHandler *	handler,
		const ThreadWorkerSessionRef &	sessionRef
	)			[protected, virtual]

Must be implemented to attach (handler) to the specified thread.

Parameters:

	thread	the QMessageTransceiverThread to attach the handler to
	handler	the QMessageTransceiverHandler to attach to the thread
	sessionRef	the AbstractReflectSession that will represent the handler inside the thread.

Returns:

B_NO_ERROR on success, or B_ERROR on failure.

Implements muscle::IMessageTransceiverMaster.

virtual void muscle::QMessageTransceiverThread::UnregisterHandler	(	QMessageTransceiverThread &	thread,
		QMessageTransceiverHandler *	handler,
		bool	emitEndMessageBatchIfNecessary
	)			[protected, virtual]

Must be implemented to detach (handler) from (thread).

Parameters:

	thread	the QMessageTransceiverThread to detach the handler from
	handler	the QMessageTransceiverHandler to detach from the thread
	emitEndMessageBatchIfNecessary	If true, and (handler) is currently in the middle of a message-batch, then this method will cause (handler) to emit an EndMessageBatch() signal before dissasociating itself from this IMessageTransceiverMaster. That way the un-registration won't break the rule that says that one EndMessageBatch() signal must always be emitted for every one BeginMessageBatch() signal.

Implements muscle::IMessageTransceiverMaster.

virtual status_t MessageTransceiverThread::StartInternalThread

(

)

[virtual, inherited]

Overridden to do some additional setup, before starting the internal thread.

Returns:

B_NO_ERROR on success, B_ERROR on error (out of memory, or thread is already running)

Reimplemented from Thread.

virtual status_t MessageTransceiverThread::AddNewSession	(	const SocketRef &	socket,
		const ThreadWorkerSessionRef &	optSessionRef
	)			[virtual, inherited]

Adds a new session that will use the given socket for its I/O.

May be called at any time, but behaves slightly differently depending on whether the internal thread is running or not. If the internal thread is running, the session will be added asynchronously to the server. If not, the call is immediately passed on through to ReflectServer::AddNewSession().

Parameters:

	socket	The TCP socket that the new session will be using, or a NULL SocketRef, if the new session is to have no associated TCP connection. This socket becomes property of this object on success.
	optSessionRef	Optional reference for a session to add. If it's a NULL reference, a default ThreadWorkerSession will be created and used. If you do specify a session here, you will want to use either a ThreadWorkerSession, a subclass of ThreadWorkerSession, or at least something that acts like one, or else things won't work correctly. The referenced session becomes sole property of the MessageTransceiverThread on success.

Returns:

B_NO_ERROR on success, or B_ERROR on failure. Note that if the internal thread is currently running, then success merely indicates that the add command was enqueued successfully, not that it was executed (yet).

virtual status_t MessageTransceiverThread::AddNewConnectSession	(	const ip_address &	targetIPAddress,
		uint16	port,
		const ThreadWorkerSessionRef &	optSessionRef,
		uint64	autoReconnectDelay = MUSCLE_TIME_NEVER
	)			[virtual, inherited]

Adds a new session that will connect out to the given IP address and port.

May be called at any time, but behaves slightly differently depending on whether the internal thread is running or not. If the internal thread is running, the session will be added asynchronously to the server. If not, the call is immediately passed on through to ReflectServer::AddNewConnectSession().

Parameters:

	targetIPAddress	IP address to connect to
	port	Port to connect to at that IP address.
	optSessionRef	optional Reference for a session to add. If it's a NULL reference, a default ThreadWorkerSession will be created and used. If you do specify a session here, you will want to use either a ThreadWorkerSession, a subclass of ThreadWorkerSession, or at least something that acts like one, or things won't work correctly. The referenced session becomes sole property of the MessageTransceiverThread on success.
	autoReconnectDelay	If specified, this is the number of microseconds after the connection is broken that an automatic reconnect should be attempted. If not specified, an automatic reconnect will not be attempted, and the session will be removed when the connection breaks. Specifying this is equivalent to calling SetAutoReconnectDelay() on (optSessionRef).

Returns:

B_NO_ERROR on success, or B_ERROR on failure. Note that if the internal thread is currently running, then success merely indicates that the add command was enqueued successfully, not that it was executed (yet).

Referenced by MessageTransceiverThread::AddNewConnectSession().

virtual status_t MessageTransceiverThread::AddNewConnectSession	(	const String &	targetHostName,
		uint16	port,
		const ThreadWorkerSessionRef &	optSessionRef,
		bool	expandLocalhost = false,
		uint64	autoReconnectDelay = MUSCLE_TIME_NEVER
	)			[virtual, inherited]

Adds a new session that will connect out to the given hostname and port.

May be called at any time, but behaves slightly differently depending on whether the internal thread is running or not. If the internal thread is running, the session will be added asynchronously to the server. If not, the call is passed immediately on through to ReflectServer::AddNewConnectSession().

Parameters:

	targetHostName	ASCII hostname or ASCII IP address to connect to. (e.g. "blah.com" or "132.239.50.8")
	port	Port to connect to at that IP address.
	optSessionRef	optional Reference for a session to add. If it's a NULL reference, a default ThreadWorkerSession will be created and used. If you do specify session here, you will want to use either a ThreadWorkerSession, a subclass of ThreadWorkerSession, or at least something that acts like one, or things won't work correctly. The referenced session becomes sole property of the MessageTransceiverThread on success.
	expandLocalhost	Passed to GetHostByName(). See GetHostByName() documentation for details. Defaults to false.
	autoReconnectDelay	If specified, this is the number of microseconds after the connection is broken that an automatic reconnect should be attempted. If not specified, an automatic reconnect will not be attempted, and the session will be removed when the connection breaks. Specifying this is equivalent to calling SetAutoReconnectDelay() on (optSessionRef).

Returns:

B_NO_ERROR on success, or B_ERROR on failure. Note that if the internal thread is currently running, then success merely indicates that the add command was enqueued successfully, not that it was executed (yet).

virtual status_t MessageTransceiverThread::PutAcceptFactory	(	uint16	port,
		const ThreadWorkerSessionFactoryRef &	optFactoryRef,
		const ip_address &	optInterfaceIP = invalidIP
	)			[virtual, inherited]

Installs a new ReflectSessionFactory onto the ReflectServer (or replaces an existing one) on the given port.

May be called at any time, but behaves slightly differently depending on whether the internal thread is running or not. If the internal thread is running, the factory will be added to the ReflectServer asynchronously; otherwise the call is passed directly through to ReflectServer::PutAcceptFactory().

Parameters:

	port	The port to place the new factory on.
	optFactoryRef	Optional reference to a factory object to use to instantiate new sessions. Note that in order for things to work as expected, (optFactory) should create only ThreadWorkerSessions (or sessions which are subclasses thereof) If left as NULL (the default), a default ThreadWorkerFactory will be created and used. The referenced factory becomes sole property of the MessageTransceiverThread on success.
	optInterfaceIP	Optional local interface address to listen on. If not specified, or if specified as (invalidIP), then connections will be accepted from all local network interfaces.

Returns:

B_NO_ERROR on success, or B_ERROR on failure. Note that if the internal thread is currently running, then success merely indicates that the put command was enqueued successfully, not that it was executed (yet).

Referenced by MessageTransceiverThread::PutAcceptFactory().

virtual status_t MessageTransceiverThread::RemoveAcceptFactory	(	uint16	port,
		const ip_address &	optInterfaceIP = invalidIP
	)			[virtual, inherited]

Removes an existing ReflectSessionFactory from the held ReflectServer.

May be called at any time, but behaves slightly differently depending on whether the internal thread is running or not. If the internal thread is running, the factory will be removed from the ReflectServer asynchronously; otherwise the call is passed directly through to ReflectServer::RemoveAcceptFactory().

Parameters:

	port	The port to remove the factory from, or zero to remove all factories.
	optInterfaceIP	Interface(s) that the specified callbacks were assigned to in their PutAcceptFactory() call. This parameter is ignored when (port) is zero.

Returns:

B_NO_ERROR on success, or B_ERROR on failure. Note that if the internal thread is currently running, then success merely indicates that the remove command was enqueued successfully, not that it was executed (yet).

status_t MessageTransceiverThread::SetDefaultDistributionPath

(

const String &

distPath

)

[inherited]

Sets our ThreadSupervisorSession's default distribution path to (optPath).

If called while the internal thread is running, the path change will be done asynchronously. This path determines which sessions get the messages sent by SendMessageToSession() if no path is specified explicitely there. Setting the path to "" indicates that you want all outgoing messages to go to all ThreadWorkerSessions. The change of target path will only affect the routing of messages enqueued after this call has returned, not ones that are currently enqueued for distribution or transmission.

Parameters:

distPath

Node path to use by default, or NULL to send to all.

Returns:

B_NO_ERROR if the set-target-path command was enqueued successfully, or B_ERROR if there was an error enqueueing it. Note that the actual change-of-path is done asynchronously.

int32 MessageTransceiverThread::GetNextEventFromInternalThread	(	uint32 &	retEventCode,
		MessageRef *	optRetMsgRef = NULL,
		String *	optFromSession = NULL,
		uint32 *	optFromFactoryID = NULL
	)			[inherited]

Call this to get the next event notification message from the internal thread.

Typically you will want to call this whenever your main thread has been notified that a new event may be pending. You should keep calling this method in a loop until it returns MTT_EVENT_NO_MORE_EVENTS; at that point it is okay to go back to waiting for the next event notification signal.

Parameters:

	retEventCode	On success, this uint32 will be set to the event code of the returned event. The event code will typically be one of the following constants: MTT_EVENT_INCOMING_MESSAGE A new message from a remote computer is ready to process MTT_EVENT_SESSION_ACCEPTED A new session has been created by one of our ReflectSessionFactory objects MTT_EVENT_SESSION_ATTACHED A new session has been attached to the local server MTT_EVENT_SESSION_CONNECTED A session on the local server has completed its connection to the remote one MTT_EVENT_SESSION_DISCONNECTED A session on the local server got disconnected from its remote peer MTT_EVENT_SESSION_DETACHED A session on the local server has detached (and been destroyed) MTT_EVENT_FACTORY_ATTACHED A ReflectSessionFactory object has been attached to the server MTT_EVENT_FACTORY_DETACHED A ReflectSessionFactory object has been detached (and been destroyed) MTT_EVENT_OUTPUT_QUEUES_DRAINED Output queues of sessions previously specified in RequestOutputQueuesDrainedNotification() have drained MTT_EVENT_SERVER_EXITED The ReflectServer event loop has terminated May return some other code if the ThreadSupervisorSession or ThreadWorkerSessions have been customized to return other message types.
	retEventCode	On successful return, the MTT_EVENT_* code for this event will be written here.
	optRetMsgRef	If non-NULL, on success the MessageRef this argument points to is written into so that it references a Message associated with the event. This is mainly used with the MTT_EVENT_INCOMING_MESSAGE event code.
	optFromSession	If non-NULL, the string that this argument points to will be have the root node path of the source AbstractReflectSession written into it (e.g. "/192.168.1.105/17").
	optFromFactoryID	If non-NULL, the uint32 that this arguments points to will have the factory ID of the source ReflectSessionFactory object written into it.

Returns:

The number of events left in the event queue (after our having removed one) on success, or -1 on failure.

status_t MessageTransceiverThread::RequestOutputQueuesDrainedNotification	(	const MessageRef &	notificationMsg,
		const char *	optDistPath = NULL,
		DrainTag *	optDrainTag = NULL
	)			[inherited]

Requests that the MessageTranceiverThread object send us a MTT_EVENT_OUTPUT_QUEUES_DRAINED event when all the specified outgoing message queues have become empty.

Which output queues are specified is handled the same way as SendMessageToSessions() does it -- if you specify a path here, sessions that match that path will be used, otherwise the default distribution path will be used.

Parameters:

	notificationMsg	MessageRef to return with the MTT_EVENT_OUTPUT_QUEUES_DRAINED event. May be a NULL ref.
	optDistPath	If non-NULL, only sessions matching this path will be watched for drainage.
	optDrainTag	If non-NULL, this DrainTag will be used to track drainage, instead of a default one. Don't supply a value for this argument unless you think you know what you are doing. ;^) On success, (optDrainTag) becomes property of this MessageTransceiverThread.

Returns:

B_NO_ERROR on success (in which case an MTT_EVENT_OUTPUT_QUEUES_DRAINED event will be forthcoming) or B_ERROR on error (out of memory).

status_t MessageTransceiverThread::SetNewInputPolicy	(	const PolicyRef &	pref,
		const char *	optDistPath = NULL
	)			[inherited]

Tells the specified worker session(s) to install a new input IOPolicy.

Parameters:

	pref	Reference to the new IOPolicy object. Since IOPolicies are generally not thread safe, the referenced IOPolicy should not be used after it has been successfully passed in via this call. May be a NULL ref to remove the existing input policy.
	optDistPath	If non-NULL, only sessions matching this path will be affected. A NULL path (the default) means affect all worker sessions.

Returns:

B_NO_ERROR on success, or B_ERROR on failure.

status_t MessageTransceiverThread::SetNewOutputPolicy	(	const PolicyRef &	pref,
		const char *	optDistPath = NULL
	)			[inherited]

Tells the specified worker session(s) to install a new output IOPolicy.

Parameters:

	pref	Reference to the new IOPolicy object. Since IOPolicies are generally not thread safe, the referenced IOPolicy should not be used after it has been successfully passed in via this call. May be a NULL ref to remove the existing output policy.
	optDistPath	If non-NULL, only sessions matching this path will be affected. A NULL path (the default) means affect all worker sessions.

Returns:

B_NO_ERROR on success, or B_ERROR on failure.

status_t MessageTransceiverThread::SetOutgoingMessageEncoding	(	int32	encoding,
		const char *	optDistPath = NULL
	)			[inherited]

Tells the specified worker session(s) to switch to a different message encoding for the Messages they are sending to the network.

Note that this only works if the workers are using the usual MessageIOGateways for their I/O. Note that ZLIB encoding is only enabled if your program is compiled with the -DMUSCLE_ENABLE_ZLIB_ENCODING compiler flag set.

Parameters:

	encoding	one of the MUSCLE_MESSAGE_ENCODING_* constant declared in MessageIOGateway.h
	optDistPath	If non-NULL, only sessions matching this path will be affected. A NULL path (the default) means affect all worker sessions.

Returns:

B_NO_ERROR on success, or B_ERROR on failure.

status_t MessageTransceiverThread::RemoveSessions

(

const char *

optDistPath = NULL

)

[inherited]

Tells the specified worker session(s) to go away.

Parameters:

optDistPath

If non-NULL, only sessions matching this path will be affected. A NULL path (the default) means all worker sessions will be destroyed.

Returns:

B_NO_ERROR on success, or B_ERROR on failure.

virtual ThreadSupervisorSessionRef MessageTransceiverThread::CreateSupervisorSession

(

)

[protected, virtual, inherited]

Creates and returns a new ThreadSupervisorSession to use to do the internal-thread-side handling of the messages this API sends.

May be overridden if you wish to use a customized subclass instead.

Returns:

a new ThreadSupervisorSession on success, or NULL on failure.

virtual ThreadWorkerSessionRef MessageTransceiverThread::CreateDefaultWorkerSession

(

)

[protected, virtual, inherited]

Creates and returns a ThreadWorkerSession object.

Called when a new session is requested (e.g. in AddNewSession(), but no session is specified by the call. This method may be overridden to customize the type of session used.

virtual ThreadWorkerSessionFactoryRef MessageTransceiverThread::CreateDefaultSessionFactory

(

)

[protected, virtual, inherited]

Creates and returns a ThreadWorkerSessionFactory object.

Called when a new factory is requested (e.g. in PutAcceptFactory(), but none is specified. This method may be overridden to customize the type of factory used.

bool Thread::IsInternalThreadRunning

(

)

const [inline, inherited]

Returns true iff the thread is considered to be running.

(Note that the thread is considered running from the time StartInternalThread() returns B_NO_ERROR until the time WaitForInternalThreadToExit() is called and returns B_NO_ERROR. Even if the thread terminates itself before then, it is still considered to be 'running' as far as we're concerned)

Definition at line 67 of file Thread.h.

virtual void Thread::ShutdownInternalThread

(

bool

waitForThread = true

)

[virtual, inherited]

Tells the internal thread to quit by sending it a NULL MessageRef, and then optionally waits for it to go away by calling WaitForInternalThreadToExit().

If the internal thread isn't running, this method is a no-op. You must call this before deleting the MessageTransceiverThread object!

Parameters:

waitForThread

if true, this method won't return until the thread is gone. Defaults to true. (if you set this to false, you'll need to also call WaitForThreadToExit() before deleting this object)

status_t Thread::WaitForInternalThreadToExit

(

)

[inherited]

Blocks and won't return until after the internal thread exits.

If you have called StartInternalThread(), you'll need to call this method (or ShutdownInternalThread()) before deleting this Thread object or calling StartInternalThread() again--even if your thread has already terminated itself! That way consistency is guaranteed and race conditions are avoided.

Returns:

B_NO_ERROR on success, or B_ERROR if the internal thread wasn't running.

virtual status_t Thread::SendMessageToInternalThread

(

const MessageRef &

msg

)

[virtual, inherited]

Puts the given message into a message queue for the internal thread to pick up, and then calls SignalInternalThread() (if necessary) to signal the internal thread that a new message is ready.

If the internal thread isn't currently running, then the MessageRef will be queued up and available to the internal thread to process when it is started.

Parameters:

msg

Reference to the message that is to be given to the internal thread.

Returns:

B_NO_ERROR on success, or B_ERROR on failure (out of memory)

virtual int32 Thread::GetNextReplyFromInternalThread	(	MessageRef &	ref,
		uint64	wakeupTime = 0
	)			[virtual, inherited]

This method attempts to retrieve the next reply message that has been sent back to the main thread by the internal thread (via SendMessageToOwner()).

Parameters:

	ref	On success, (ref) will be a reference to the new reply message.
	wakeupTime	Time at which this method should stop blocking and return, even if there is no new reply message ready. If this value is 0 (the default) or otherwise less than the current time (as returned by GetRunTime64()), then this method does a non-blocking poll of the reply queue. If (wakeuptime) is set to MUSCLE_TIME_NEVER, then this method will block indefinitely, until a new reply is ready.

See also:

GetOwnerSocketSet() for advanced control of this method's behaviour

Returns:

The number of Messages left in the reply queue on success, or -1 on failure (The call timed out without any replies ever showing up)

Queue<MessageRef>* Thread::LockAndReturnMessageQueue

(

)

[inherited]

Locks the internal thread's message queue and returns a pointer to it.

Since the queue is locked, you may examine or modify the queue safely. Once this method has returned successfully, you are responsible for unlocking the message queue again by calling UnlockMessageQueue(). If you don't, the Thread will remain locked and stuck!

Returns:

a pointer to our internal Message queue, on success, or NULL on failure (couldn't lock)

status_t Thread::UnlockMessageQueue

(

)

[inherited]

Unlocks our internal message queue, so that the internal thread can again pop messages off of it.

Should be called exactly once after each successful call to LockAndReturnMessageQueue(). After this call returns, it is no longer safe to use the pointer that was previously returned by LockAndReturnMessageQueue().

Returns:

B_NO_ERROR on success, or B_ERROR if the unlock call failed (perhaps it wasn't locked?)

Queue<MessageRef>* Thread::LockAndReturnReplyQueue

(

)

[inherited]

Locks this Thread's reply queue and returns a pointer to it.

Since the queue is locked, you may examine or modify the queue safely. Once this method has returned successfully, you are responsible for unlocking the message queue again by calling UnlockReplyQueue(). If you don't, the Thread will remain locked and stuck!

Returns:

a pointer to our internal reply queue on success, or NULL on failure (couldn't lock)

status_t Thread::UnlockReplyQueue

(

)

[inherited]

Unlocks the reply message queue, so that the internal thread can again append messages to it.

Should be called exactly once after each successful call to LockAndReturnReplyQueue(). After this call returns, it is no longer safe to use the pointer that was previously returned by LockAndReturnReplyQueue().

Returns:

B_NO_ERROR on success, or B_ERROR if the unlock call failed (perhaps it wasn't locked?)

const SocketRef& Thread::GetOwnerWakeupSocket

(

)

[inherited]

Returns the socket that the main thread may select() for read on for wakeup-notification bytes.

This Thread object's thread-signalling sockets will be allocated by this method if they aren't already allocated.

<