#include <SDLMessageTransceiverThread.h>
Inheritance diagram for SDLMessageTransceiverThread:
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 Member Functions | |
| SDLMessageTransceiverThread () | |
| Constructor. | |
| virtual status_t | StartInternalThread () |
| Overridden to do some additional setup, before starting the internal thread. | |
| virtual status_t | SendMessageToSessions (const MessageRef &msgRef, const char *optDistPath=NULL) |
| Asynchronously sends the given message to the specified target session(s) inside the held ReflectServer. | |
| 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. | |
| virtual void | Reset () |
| Stops the internal thread if it is running, destroys internal the internal ReflectServer object, and more or less make this MessageTransceiverThread look like it had just been constructed anew. | |
| 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 ¬ificationMsg, 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 SDLEvent. | |
| 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. | |
Definition at line 16 of file SDLMessageTransceiverThread.h.
anonymous enum [inherited] |
Enumeration of the socket sets that are available for blocking on; used in GetOwnerSocketSet() and GetInternalSocketSet() calls.
| virtual status_t MessageTransceiverThread::StartInternalThread | ( | ) | [virtual, inherited] |
Overridden to do some additional setup, before starting the internal thread.
Reimplemented from Thread.
| virtual status_t MessageTransceiverThread::SendMessageToSessions | ( | const MessageRef & | msgRef, | |
| const char * | optDistPath = NULL | |||
| ) | [virtual, inherited] |
Asynchronously sends the given message to the specified target session(s) inside the held ReflectServer.
May be called at any time; if called while the internal thread isn't running, the given message will be queued up and delivered when the internal thread is started.
| msgRef | Reference to the message to send | |
| optDistPath | Optional node path to match against to decide which ThreadWorkerSessions to send to. If left as NULL, the default distribution path will be used. |
Reimplemented in muscle::QMessageTransceiverThread.
| 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().
| 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. |
| 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().
| 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). |
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().
| 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). |
| 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().
| 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. |
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().
| 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. |
| 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.
| distPath | Node path to use by default, or NULL to send to all. |
| 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.
| 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:
| |
| 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. |
| 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.
| 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. |
| status_t MessageTransceiverThread::SetNewInputPolicy | ( | const PolicyRef & | pref, | |
| const char * | optDistPath = NULL | |||
| ) | [inherited] |
Tells the specified worker session(s) to install a new input IOPolicy.
| 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. |
| status_t MessageTransceiverThread::SetNewOutputPolicy | ( | const PolicyRef & | pref, | |
| const char * | optDistPath = NULL | |||
| ) | [inherited] |
Tells the specified worker session(s) to install a new output IOPolicy.
| 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. |
| 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.
| 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. |
| status_t MessageTransceiverThread::RemoveSessions | ( | const char * | optDistPath = NULL |
) | [inherited] |
Tells the specified worker session(s) to go away.
| optDistPath | If non-NULL, only sessions matching this path will be affected. A NULL path (the default) means all worker sessions will be destroyed. |
| 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.
| 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)
| 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!
| 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.
| 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.
| msg | Reference to the message that is to be given to the internal thread. |
| 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()).
| 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. |
| 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!
| 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().
| 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!
| 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().
| 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.
This function returns a reference to one of the three socket-sets that GetNextReplyFromInternalThread() will optionally use to determine whether to return early.
By default, all of the socket-sets are empty, and GetNextReplyFromInternalThread() will return only when a new Message has arrived from the internal thread, or when the timeout period has elapsed.
However, in some cases it is useful to have GetNextReplyFromInternalThread() return under other conditions as well, such as when a specified socket becomes ready-to-read-from or ready-to-write-to. You can specify that a socket should be watched in this manner, by adding that socket to the appropriate socket set(s). For example, to tell GetNextReplyFromInternalThread() to always return when mySocket is ready to be written to, you would add mySocket to the SOCKET_SET_WRITE set, like this:
_thread.GetOwnerSocketSet(SOCKET_SET_WRITE).Put(mySocket, false);
(This only needs to be done once) After GetNextReplyFromInternalThread() returns, you can determine whether your socket is ready-to-write-to by checking its associated value in the table, like this:
bool canWrite = false; _thread.GetOwnerSocketSet(SOCKET_SET_WRITE).Get(mySocket, canWrite); if (canWrite) printf("Socket is ready to be written to!\n");
| socketSet | SOCKET_SET_* indicating which socket-set to return a reference to. |
| virtual status_t Thread::MessageReceivedFromOwner | ( | const MessageRef & | msgRef, | |
| uint32 | numLeft | |||
| ) | [protected, virtual, inherited] |
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.
Default implementation does nothing, and returns B_NO_ERROR if (msgRef) is valid, or B_ERROR if (msgRef) is a NULL reference.
| msgRef | Reference to the just-received Message object. | |
| numLeft | Number of Messages still left in the owner's message queue. |
| status_t Thread::SendMessageToOwner | ( | const MessageRef & | replyRef | ) | [protected, inherited] |
May be called by the internal thread to send a Message back to the owning thread.
Puts the given MessageRef into the replies queue, and then calls SignalOwner() (if necessary) to notify the main thread that replies are pending.
| replyRef | MessageRef to send back to the owning thread. |
| virtual int32 Thread::WaitForNextMessageFromOwner | ( | MessageRef & | ref, | |
| uint64 | wakeupTime = MUSCLE_TIME_NEVER | |||
| ) | [protected, virtual, inherited] |
This method is meant to be called by the internally held thread.
It will attempt retrieve the next message that has been sent to the thread via SendMessageToThread().
| ref | On success, (ref) will be set to be a reference to the retrieved Message. | |
| wakeupTime | Time at which this method should stop blocking and return, even if there is no new message ready. If this value is 0 or otherwise less than the current time (as returned by GetRunTime64()), then this method does a non-blocking poll of the queue. If (wakeuptime) is set to MUSCLE_TIME_NEVER (the default value), then this method will block indefinitely, until a Message is ready. |
| virtual void Thread::SignalInternalThread | ( | ) | [protected, virtual, inherited] |
Called by SendMessageToThread() whenever there is a need to wake up the internal thread so that it will look at its reply queue.
Default implementation sends a byte on a socket to implement this, but you can override this method to do it a different way if you need to.
| const SocketRef& Thread::GetInternalThreadWakeupSocket | ( | ) | [protected, inherited] |
Returns the socket that the internal 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.
| status_t Thread::LockSignalling | ( | ) | [inline, protected, inherited] |
Locks the lock we use to serialize calls to SignalInternalThread() and SignalOwner().
Be sure to call UnlockSignallingLock() when you are done with the lock.
Definition at line 264 of file Thread.h.
References Mutex::Lock().
| status_t Thread::UnlockSignalling | ( | ) | [inline, protected, inherited] |
Unlocks the lock we use to serialize calls to SignalInternalThread() and SignalOwner().
Definition at line 269 of file Thread.h.
References Mutex::Unlock().
| Hashtable<SocketRef, bool>& Thread::GetInternalSocketSet | ( | uint32 | socketSet | ) | [inline, protected, inherited] |
This function returns a reference to one of the three socket-sets that WaitForNextMessageFromOwner() will optionally use to determine whether to return early.
By default, all of the socket-sets are empty, and WaitForNextMessageFromOwner() will return only when a new Message has arrived from the owner thread, or when the timeout period has elapsed.
However, in some cases it is useful to have WaitForNextMessageFromOwner() return under other conditions as well, such as when a specified socket becomes ready-to-read-from or ready-to-write-to. You can specify that a socket should be watched in this manner, by adding that socket to the appropriate socket set(s). For example, to tell WaitForNextMessageFromOwner() to always return when mySocket is ready to be written to, you would add mySocket to the SOCKET_SET_WRITE set, like this:
_thread.GetInternalSocketSet(SOCKET_SET_WRITE).Put(mySocket, false);
(This only needs to be done once) After WaitForNextMessageFromOwner() returns, you can determine whether your socket is ready-to-write-to by checking its associated value in the table, like this:
bool canWrite = false; _thread.GetInternalSocketSet(SOCKET_SET_WRITE).Get(mySocket, canWrite); if (canWrite) printf("Socket is ready to be written to!\n");
| socketSet | SOCKET_SET_* indicating which socket-set to return a reference to. |
1.5.1