#include <PlainTextMessageIOGateway.h>
Inheritance diagram for PlainTextMessageIOGateway:
Public Member Functions | |
| PlainTextMessageIOGateway () | |
| Default constructor. | |
| virtual | ~PlainTextMessageIOGateway () |
| Destructor. | |
| virtual bool | HasBytesToOutput () const |
| Should return true if this gateway has bytes that are queued up and waiting to be sent across the wire. | |
| virtual void | Reset () |
| This method must resets the gateway's encoding and decoding state to its default state. | |
| virtual void | SetOutgoingEndOfLineString (const char *str) |
| Set the end-of-line string to be attached to outgoing text lines. | |
| void | SetFlushPartialIncomingLines (bool f) |
| If set to true, then any "leftover" text after the last carriage return will be added to the incoming Message. | |
| bool | GetFlushPartialIncomingLines () const |
| Returns the flush-partial-incoming-lines value, as set by SetFlushPartialIncomingLines(). | |
| void | FlushInput (AbstractGatewayMessageReceiver &receiver) |
| Force any pending input to be immediately flushed out. | |
| status_t | AddOutgoingMessage (const MessageRef &messageRef) |
| Appends the given message reference to the end of our list of outgoing messages to send. | |
| int32 | DoOutput (uint32 maxBytes=MUSCLE_NO_LIMIT) |
| Writes some of our outgoing message bytes to the wire. | |
| int32 | DoInput (AbstractGatewayMessageReceiver &receiver, uint32 maxBytes=MUSCLE_NO_LIMIT) |
| Reads some more incoming message bytes from the wire. | |
| virtual bool | IsReadyForInput () const |
| Should return true if this gateway is willing to receive from bytes from the wire. | |
| virtual uint64 | GetOutputStallLimit () const |
| Returns the number of microseconds that output to this gateway's client should be allowed to stall for. | |
| virtual void | Shutdown () |
| Shuts down the gateway. | |
| void | SetFlushOnEmpty (bool flush) |
| By default, the AbstractMessageIOGateway calls Flush() on its DataIO's output stream whenever the last outgoing message in the outgoing message queue is sent. | |
| bool | GetFlushOnEmpty () const |
| Accessor for the current state of the FlushOnEmpty flag. | |
| Queue< MessageRef > & | GetOutgoingMessageQueue () |
| Returns A reference to our outgoing messages queue. | |
| const Queue< MessageRef > & | GetOutgoingMessageQueue () const |
| Returns A const reference to our outgoing messages queue. | |
| void | SetDataIO (const DataIORef &ref) |
| Installs (ref) as the DataIO object we will use for our I/O. | |
| const DataIORef & | GetDataIO () const |
| As above, but returns a reference instead of the raw pointer. | |
| bool | IsHosed () const |
| Returns true iff we are hosed--that is, we've experienced an unrecoverable error. | |
| virtual status_t | ExecuteSynchronousMessaging (AbstractGatewayMessageReceiver *optReceiver, uint64 timeoutPeriod=MUSCLE_TIME_NEVER) |
| This is a convenience method for when you want to do simple synchronous (RPC-style) communications. | |
| void | IncrementRefCount () const |
| Increments the counter and returns true iff the new value is zero. | |
| bool | DecrementRefCount () const |
| Decrements the counter and returns true iff the new value is zero. | |
| void | SetManager (AbstractObjectManager *manager) |
| Sets the recycle-pointer for this object. | |
| AbstractObjectManager * | GetManager () const |
| Returns this object's current recyler pointer. | |
| uint32 | GetRefCount () const |
| Returns this object's current reference count. | |
| virtual uint64 | GetPulseTime (uint64 now, uint64 prevResult) |
| This method can be overridden to tell the PulseNodeManager when we would like to have our Pulse() method called. | |
| virtual void | Pulse (uint64 now, uint64 scheduledTime) |
| Will be called at the time specified previously by GetPulseTime(). | |
| status_t | PutPulseChild (PulseNode *child) |
| Adds the given child into our set of child PulseNodes. | |
| status_t | RemovePulseChild (PulseNode *child) |
| Attempts to remove the given child from our set of child PulseNodes. | |
| void | ClearPulseChildren () |
| Removes all children from our set of child PulseNodes. | |
| bool | ContainsPulseChild (PulseNode *child) const |
| Returns true iff the given child is in our set of child PulseNodes. | |
| uint64 | GetScheduledPulseTime () const |
| Returns when this object wants its call to Pulse() scheduled next, or MUSCLE_TIME_NEVER if it has no call to Pulse() currently scheduled. | |
| uint64 | GetCycleStartTime () const |
| Returns the run-time at which the PulseNodeManager started calling our callbacks. | |
| void | SetSuggestedMaximumTimeSlice (uint64 maxUsecs) |
| Sets the maximum number of microseconds that this class should allow its callback methods to execute for (relative to the cycle start time, as shown above). | |
| uint64 | GetSuggestedMaximumTimeSlice () const |
| Returns the current suggested maximum duration of our time slice, or MUSCLE_TIME_NEVER if there is no suggested limit. | |
| bool | IsSuggestedTimeSliceExpired () const |
| Convenience method -- returns true iff the current value of the run-time clock (GetRunTime64()) indicates that our suggested time slice has expired. | |
Protected Member Functions | |
| virtual int32 | DoOutputImplementation (uint32 maxBytes=MUSCLE_NO_LIMIT) |
| Writes some of our outgoing message bytes to the wire. | |
| virtual int32 | DoInputImplementation (AbstractGatewayMessageReceiver &receiver, uint32 maxBytes=MUSCLE_NO_LIMIT) |
| Reads some more incoming message bytes from the wire. | |
| status_t | EnsureBufferSize (uint8 **bufPtr, uint32 *bufSize, uint32 desiredSize, uint32 copySize) |
| Convenience method to allocate or reallocate a buffer. | |
| void | FreeLargeBuffer (uint8 **bufPtr, uint32 *bufSize) |
| Convenience method; frees the given buffer and resets it to NULL, if the buffer is greater than 10 kilobytes big. | |
| void | SetHosed () |
| Call this method to flag this gateway as hosed--that is, to say that an unrecoverable error has occurred. | |
| virtual bool | IsStillAwaitingSynchronousMessagingReply () const |
| Called by ExecuteSynchronousMessaging() to see if we are still awaiting our reply Messages. | |
| virtual void | SynchronousMessageReceivedFromGateway (const MessageRef &msg, void *userData, AbstractGatewayMessageReceiver &r) |
| Called by ExecuteSynchronousMessaging() when a Message is received. | |
| virtual void | SynchronousAfterMessageReceivedFromGateway (const MessageRef &msg, void *userData, AbstractGatewayMessageReceiver &r) |
| Called by ExecuteSynchronousMessaging() after a Message is received. | |
| virtual void | SynchronousBeginMessageReceivedFromGatewayBatch (AbstractGatewayMessageReceiver &r) |
| Called by ExecuteSynchronousMessaging() when a batch of Messages is about to be received. | |
| virtual void | SynchronousEndMessageReceivedFromGatewayBatch (AbstractGatewayMessageReceiver &r) |
| Called by ExecuteSynchronousMessaging() when all Messages in a batch have been received. | |
| void | InvalidatePulseTime (bool clearPrevResult=true) |
| Sets a flag to indicate that GetPulseTime() should be called on this object. | |
It can be used for "telnet-style" net interactions. Incoming and outgoing messages may have one or more strings in their PR_NAME_TEXT_LINE field. Each of these strings represents a line of text (separator chars not included)
Definition at line 22 of file PlainTextMessageIOGateway.h.
| virtual bool PlainTextMessageIOGateway::HasBytesToOutput | ( | ) | const [virtual] |
Should return true if this gateway has bytes that are queued up and waiting to be sent across the wire.
Should return false if there are no bytes ready to send, or if the connection has been closed or hosed.
Implements AbstractMessageIOGateway.
| virtual void PlainTextMessageIOGateway::Reset | ( | ) | [virtual] |
This method must resets the gateway's encoding and decoding state to its default state.
Any partially completed sends and receives should be cleared, so that the gateway is ready to send and receive fresh data streams. Default implementation clears the "hosed" flag and clears the outgoing-Messages queue. Subclasses should override this to reset their parse-state variables appropriately too.
Reimplemented from AbstractMessageIOGateway.
| virtual void PlainTextMessageIOGateway::SetOutgoingEndOfLineString | ( | const char * | str | ) | [inline, virtual] |
Set the end-of-line string to be attached to outgoing text lines.
| str | New end-of-line string to use. (Default value is "\r\n") |
Definition at line 37 of file PlainTextMessageIOGateway.h.
| void PlainTextMessageIOGateway::SetFlushPartialIncomingLines | ( | bool | f | ) | [inline] |
If set to true, then any "leftover" text after the last carriage return will be added to the incoming Message.
If false (the default), then incoming text without a carriage return will be buffered internally until the next carriage return is received.
Definition at line 44 of file PlainTextMessageIOGateway.h.
| void PlainTextMessageIOGateway::FlushInput | ( | AbstractGatewayMessageReceiver & | receiver | ) |
Force any pending input to be immediately flushed out.
| receiver | The object to call MessageReceivedFromGateway() on, if necessary. |
| virtual int32 PlainTextMessageIOGateway::DoOutputImplementation | ( | uint32 | maxBytes = MUSCLE_NO_LIMIT |
) | [protected, virtual] |
Writes some of our outgoing message bytes to the wire.
Not guaranteed to write all outgoing messages (it will try not to block)
| maxBytes | optional limit on the number of bytes that should be sent out. Defaults to MUSCLE_NO_LIMIT (which is a very large number) |
Implements AbstractMessageIOGateway.
| virtual int32 PlainTextMessageIOGateway::DoInputImplementation | ( | AbstractGatewayMessageReceiver & | receiver, | |
| uint32 | maxBytes = MUSCLE_NO_LIMIT | |||
| ) | [protected, virtual] |
Reads some more incoming message bytes from the wire.
Any time a new Message is received, MessageReceivedFromGateway() should be called on the provided AbstractGatewayMessageReceiver to notify him about it.
| receiver | An object to call MessageReceivedFromGateway() on whenever a new incoming Message is available. | |
| maxBytes | optional limit on the number of bytes that should be read in. Defaults to MUSCLE_NO_LIMIT (which is a very large number) Tries not to block, but may (if the held DataIO object is in blocking mode) |
Implements AbstractMessageIOGateway.
| status_t AbstractMessageIOGateway::AddOutgoingMessage | ( | const MessageRef & | messageRef | ) | [inline, inherited] |
Appends the given message reference to the end of our list of outgoing messages to send.
Never blocks.
| messageRef | A reference to the Message to send out through the gateway. |
Definition at line 120 of file AbstractMessageIOGateway.h.
| int32 AbstractMessageIOGateway::DoOutput | ( | uint32 | maxBytes = MUSCLE_NO_LIMIT |
) | [inline, inherited] |
Writes some of our outgoing message bytes to the wire.
Not guaranteed to write all outgoing messages (it will try not to block)
| maxBytes | optional limit on the number of bytes that should be sent out. Defaults to MUSCLE_NO_LIMIT (which is a very large number) |
Definition at line 131 of file AbstractMessageIOGateway.h.
References AbstractMessageIOGateway::DoOutputImplementation().
| int32 AbstractMessageIOGateway::DoInput | ( | AbstractGatewayMessageReceiver & | receiver, | |
| uint32 | maxBytes = MUSCLE_NO_LIMIT | |||
| ) | [inline, inherited] |
Reads some more incoming message bytes from the wire.
Any time a new Message is received, MessageReceivedFromGateway() should be called on the provided AbstractGatewayMessageReceiver to notify him about it.
| receiver | An object to call MessageReceivedFromGateway() on whenever a new incoming Message is available. | |
| maxBytes | optional limit on the number of bytes that should be read in. Defaults to MUSCLE_NO_LIMIT (which is a very large number) Tries not to block, but may (depending on implementation) |
Definition at line 146 of file AbstractMessageIOGateway.h.
References AbstractGatewayMessageReceiver::DoInputBegins(), AbstractGatewayMessageReceiver::DoInputEnds(), and AbstractMessageIOGateway::DoInputImplementation().
| virtual bool AbstractMessageIOGateway::IsReadyForInput | ( | ) | const [virtual, inherited] |
Should return true if this gateway is willing to receive from bytes from the wire.
Should return false if (for some reason) the gateway doesn't want to read any bytes right now. The default implementation of this method always returns true.
| virtual uint64 AbstractMessageIOGateway::GetOutputStallLimit | ( | ) | const [virtual, inherited] |
Returns the number of microseconds that output to this gateway's client should be allowed to stall for.
If the output stalls for longer than this amount of time, the connection will be closed. Return MUSCLE_TIME_NEVER to disable stall limit checking. Default behaviour is to forward this call to the held DataIO object.
| virtual void AbstractMessageIOGateway::Shutdown | ( | ) | [virtual, inherited] |
Shuts down the gateway.
Default implementation calls Shutdown() on the held DataIO object.
| void AbstractMessageIOGateway::SetFlushOnEmpty | ( | bool | flush | ) | [inherited] |
By default, the AbstractMessageIOGateway calls Flush() on its DataIO's output stream whenever the last outgoing message in the outgoing message queue is sent.
Call SetFlushOnEmpty(false) to inhibit this behavior (e.g. for bandwidth efficiency when low message latency is not a requirement).
| flush | If true, auto-flushing will be enabled. If false, it will be disabled. |
| void AbstractMessageIOGateway::SetDataIO | ( | const DataIORef & | ref | ) | [inline, inherited] |
Installs (ref) as the DataIO object we will use for our I/O.
Typically called by the ReflectServer object.
Definition at line 212 of file AbstractMessageIOGateway.h.
| virtual status_t AbstractMessageIOGateway::ExecuteSynchronousMessaging | ( | AbstractGatewayMessageReceiver * | optReceiver, | |
| uint64 | timeoutPeriod = MUSCLE_TIME_NEVER | |||
| ) | [virtual, inherited] |
This is a convenience method for when you want to do simple synchronous (RPC-style) communications.
This method will run its own little event loop and not return until all of this I/O gateway's outgoing Messages have been sent out. Subclasses of the AbstractMessageIOGateway class that support doing so may augment this method's logic so that this method does not return until the corresponding reply Messages have been received and passed to (optReceiver) as well, but since that functionality is dependent on the particulars of the gateway subclass's protocol, this base method does not do that.
| optReceiver | If non-NULL, then any Messages are received from the remote end of the during the time that ExecuteSynchronousMessaging() is executing will be passed to (optReceiver)'s MessageReceivedFromGateway() method. If NULL, then no data will be read from the socket. | |
| timeoutPeriod | A timeout period for this method. If left as MUSCLE_TIME_NEVER (the default), then no timeout is applied. If set to another value, then this method will return B_ERROR after (timeoutPeriod) microseconds if the operation hasn't already completed by then. |
Reimplemented in MessageIOGateway.
| status_t AbstractMessageIOGateway::EnsureBufferSize | ( | uint8 ** | bufPtr, | |
| uint32 * | bufSize, | |||
| uint32 | desiredSize, | |||
| uint32 | copySize | |||
| ) | [protected, inherited] |
Convenience method to allocate or reallocate a buffer.
When this method returns successfully, (*bufPtr) will point to a buffer that is at least (desiredSize) bytes long.
| bufPtr | points to a pointer to the buffer. (May point to a NULL pointer if no buffer is currently allocated) | |
| bufSize | points to the current size of the buffer. On return, this value is changed to reflect the new buffer size. | |
| desiredSize | indicates the minimum new buffer size required. | |
| copySize | indicates the number of bytes to copy out of the old buffer and into the new one, if a reallocation is necessary. |
| void AbstractMessageIOGateway::FreeLargeBuffer | ( | uint8 ** | bufPtr, | |
| uint32 * | bufSize | |||
| ) | [protected, inherited] |
Convenience method; frees the given buffer and resets it to NULL, if the buffer is greater than 10 kilobytes big.
(Buffers smaller than that are not effected, since it's probably cheaper to keep them around and avoid having to deallocate and reallocate them all the time).
| bufPtr | points to a pointer to the buffer. (May point to a NULL pointer if no buffer is currently allocated). The pointer may be set to NULL if the buffer was freed. | |
| bufSize | points to the size-value of the buffer. May be set to 0 if the buffer was freed. |
| virtual bool AbstractMessageIOGateway::IsStillAwaitingSynchronousMessagingReply | ( | ) | const [inline, protected, virtual, inherited] |
Called by ExecuteSynchronousMessaging() to see if we are still awaiting our reply Messages.
Default implementation calls HasBytesToOutput() and returns that value.
Reimplemented in MessageIOGateway.
Definition at line 301 of file AbstractMessageIOGateway.h.
References AbstractMessageIOGateway::HasBytesToOutput().
| virtual void AbstractMessageIOGateway::SynchronousMessageReceivedFromGateway | ( | const MessageRef & | msg, | |
| void * | userData, | |||
| AbstractGatewayMessageReceiver & | r | |||
| ) | [inline, protected, virtual, inherited] |
Called by ExecuteSynchronousMessaging() when a Message is received.
Default implementation just passes the call on to the like-named method in (r)
Reimplemented in MessageIOGateway.
Definition at line 304 of file AbstractMessageIOGateway.h.
References AbstractGatewayMessageReceiver::MessageReceivedFromGateway().
| virtual void AbstractMessageIOGateway::SynchronousAfterMessageReceivedFromGateway | ( | const MessageRef & | msg, | |
| void * | userData, | |||
| AbstractGatewayMessageReceiver & | r | |||
| ) | [inline, protected, virtual, inherited] |
Called by ExecuteSynchronousMessaging() after a Message is received.
Default implementation just passes the call on to the like-named method in (r)
Definition at line 307 of file AbstractMessageIOGateway.h.
References AbstractGatewayMessageReceiver::AfterMessageReceivedFromGateway().
| virtual void AbstractMessageIOGateway::SynchronousBeginMessageReceivedFromGatewayBatch | ( | AbstractGatewayMessageReceiver & | r | ) | [inline, protected, virtual, inherited] |
Called by ExecuteSynchronousMessaging() when a batch of Messages is about to be received.
Default implementation just passes the call on to the like-named method in (r)
Definition at line 310 of file AbstractMessageIOGateway.h.
References AbstractGatewayMessageReceiver::BeginMessageReceivedFromGatewayBatch().
| virtual void AbstractMessageIOGateway::SynchronousEndMessageReceivedFromGatewayBatch | ( | AbstractGatewayMessageReceiver & | r | ) | [inline, protected, virtual, inherited] |
Called by ExecuteSynchronousMessaging() when all Messages in a batch have been received.
Default implementation just passes the call on to the like-named method in (r)
Definition at line 313 of file AbstractMessageIOGateway.h.
References AbstractGatewayMessageReceiver::EndMessageReceivedFromGatewayBatch().
| void RefCountable::IncrementRefCount | ( | ) | const [inline, inherited] |
Increments the counter and returns true iff the new value is zero.
Thread safe.
Definition at line 32 of file RefCount.h.
References AtomicCounter::AtomicIncrement().
| bool RefCountable::DecrementRefCount | ( | ) | const [inline, inherited] |
Decrements the counter and returns true iff the new value is zero.
Thread safe.
Definition at line 35 of file RefCount.h.
References AtomicCounter::AtomicDecrement().
| void RefCountable::SetManager | ( | AbstractObjectManager * | manager | ) | [inline, inherited] |
Sets the recycle-pointer for this object.
If set to non-NULL, this pointer is used by the ObjectPool class to recycle this object when it is no longer in use, so as to avoid the overhead of having to delete it and re-create it later on. The RefCountable class itself does nothing with this pointer. Default value is NULL.
| manager | Pointer to the new manager object to use, or NULL to use no manager. |
Definition at line 44 of file RefCount.h.
| uint32 RefCountable::GetRefCount | ( | ) | const [inline, inherited] |
Returns this object's current reference count.
Note that the value returned by this method is volatile in multithreaded environments, so it may already be wrong by the time it is returned. Be careful!
Definition at line 54 of file RefCount.h.
References AtomicCounter::GetCount().
| virtual uint64 PulseNode::GetPulseTime | ( | uint64 | now, | |
| uint64 | prevResult | |||
| ) | [virtual, inherited] |
This method can be overridden to tell the PulseNodeManager when we would like to have our Pulse() method called.
This method is guaranteed to be called only during the following times:
| now | The current wall-clock time in microseconds, for convenience. | |
| prevResult | The value that this method returned the last time it was called. The very first time this method is called, this value will be passed in as MUSCLE_TIME_NEVER. |
Reimplemented in AbstractReflectSession, and RateLimitSessionIOPolicy.
| virtual void PulseNode::Pulse | ( | uint64 | now, | |
| uint64 | scheduledTime | |||
| ) | [virtual, inherited] |
Will be called at the time specified previously by GetPulseTime().
GetPulseTime() will be called again immediately after this call, to check if you want to schedule another Pulse() call for later. Default implementation is a no-op.
| now | The current wall-clock time-value in microseconds, for convenience. | |
| scheduledTime | The time this Pulse() call was scheduled to occur at, in microseconds, as previously returned by GetPulseTime(). Note that unless your computer is infinitely fast, this time will always be at least a bit less than (now), since there is a delay between when the program gets woken up to service the next Pulse() call, and when the call actually happens. (you may be able to use this value to compensate for the slippage, if it bothers you) |
Reimplemented in AbstractReflectSession, and RateLimitSessionIOPolicy.
| status_t PulseNode::PutPulseChild | ( | PulseNode * | child | ) | [inherited] |
Adds the given child into our set of child PulseNodes.
Any PulseNode in our set of children will have its pulsing needs taken care of by us, but it is not considered "owned" by this PulseNode--it will not be deleted when we are.
| child | The child to place into our set of child PulseNodes. |
| status_t PulseNode::RemovePulseChild | ( | PulseNode * | child | ) | [inherited] |
Attempts to remove the given child from our set of child PulseNodes.
| child | The child to remove |
| bool PulseNode::ContainsPulseChild | ( | PulseNode * | child | ) | const [inline, inherited] |
Returns true iff the given child is in our set of child PulseNodes.
| child | the child to look for. |
Definition at line 84 of file PulseNode.h.
References PulseNode::_parent.
| uint64 PulseNode::GetCycleStartTime | ( | ) | const [inline, inherited] |
Returns the run-time at which the PulseNodeManager started calling our callbacks.
Useful for any object that wants to limit the maximum duration of its timeslice in the PulseNodeManager's event loop.
Definition at line 95 of file PulseNode.h.
| void PulseNode::SetSuggestedMaximumTimeSlice | ( | uint64 | maxUsecs | ) | [inline, inherited] |
Sets the maximum number of microseconds that this class should allow its callback methods to execute for (relative to the cycle start time, as shown above).
Note that this value is merely a suggestion; it remains up to the subclass's callback methods to ensure that the suggestion is actually followed.
| maxUsecs | Maximum number of microseconds that the time slice should last for. If set to MUSCLE_TIME_NEVER, that indicates that there is no suggested limit. |
Definition at line 104 of file PulseNode.h.
| uint64 PulseNode::GetSuggestedMaximumTimeSlice | ( | ) | const [inline, inherited] |
Returns the current suggested maximum duration of our time slice, or MUSCLE_TIME_NEVER if there is no suggested limit.
Default value is MUSCLE_TIME_NEVER.
Definition at line 109 of file PulseNode.h.
| bool PulseNode::IsSuggestedTimeSliceExpired | ( | ) | const [inline, inherited] |
Convenience method -- returns true iff the current value of the run-time clock (GetRunTime64()) indicates that our suggested time slice has expired.
This method is cheap to call often.
Definition at line 115 of file PulseNode.h.
| void PulseNode::InvalidatePulseTime | ( | bool | clearPrevResult = true |
) | [protected, inherited] |
Sets a flag to indicate that GetPulseTime() should be called on this object.
Call this whenever you've decided to reschedule your pulse time outside of a Pulse() event.
| clearPrevResult | if true, this call will also clear the stored prevResult value, so that the next time GetPulseTime() is called, prevResult is passed in as MUSCLE_TIME_NEVER. If false, the prevResult value will be left alone. |
Referenced by AbstractReflectSession::SetAutoReconnectDelay().
1.5.1