YAMI4 - C++ general-purpose interface
yami::outgoing_message Class Reference

Outgoing message. More...

#include <outgoing_message.h>

List of all members.

Public Types

typedef long long outgoing_message_id
 Outgoing message identifier type.

Public Member Functions

 outgoing_message ()
 Constructor.
message_state get_state () const
 Returns the state of this message.
message_state get_state (std::size_t &sent_bytes, std::size_t &total_byte_count) const
 Returns the state of this message.
void wait_for_transmission () const
 Waits for the transmission to finish.
bool wait_for_transmission (std::size_t relative_timeout) const
 Waits for the transmission to finish or until timeout expires.
bool wait_for_transmission_absolute (unsigned long long timeout) const
 Waits for the transmission to finish or until timeout expires.
void wait_for_completion () const
 Waits for the full message roundtrip.
bool wait_for_completion (std::size_t relative_timeout) const
 Waits for the message roundtrip or until timeout expires.
bool wait_for_completion_absolute (unsigned long long timeout) const
 Waits for the message roundtrip or until timeout expires.
const parametersget_reply () const
 Provides access to the reply content.
const std::vector< char > & get_raw_reply () const
 Provides access to the reply content.
parametersextract_reply ()
 Extracts the reply content.
const std::string & get_exception_msg () const
 Returns the exception message.
outgoing_message_id get_message_id () const
 Returns the internal message id.

Detailed Description

The handler allowing to track the progress of outgoing message, inspect its state and to obtain the reply content.

Note: The objects of this class can be safely used from multiple threads.


Constructor & Destructor Documentation

outgoing_message::outgoing_message ( )

Creates uninitialized outgoing message object.


Member Function Documentation

message_state outgoing_message::get_state ( std::size_t &  sent_bytes,
std::size_t &  total_byte_count 
) const

This function allows to inspect the progress of the message transmission. During transmission the sent_bytes value is always smaller than total_byte_count. When these two values become equal, it means that the transmission was either succesful or abandoned.

Parameters:
sent_bytesThe number of bytes that were already sent for this message.
total_byte_countThe total number of bytes that should be sent for this message.
void outgoing_message::wait_for_transmission ( ) const

Waits for the transmission to finish - that is, to either send all the message data or to abandon it. After this function returns the state of the message is either transmitted, abandoned, replied or rejected.

bool outgoing_message::wait_for_transmission ( std::size_t  relative_timeout) const

Waits for the transmission to finish or until the given relative timeout expires.

Parameters:
relative_timeoutThe relative timeout in milliseconds.
Returns:
  • true if the wait completed before the timeout
  • false if the timeout expired before the message was fully transmitted
bool outgoing_message::wait_for_transmission_absolute ( unsigned long long  timeout) const

Waits for the transmission to finish or until the given absolute timeout expires.

Parameters:
timeoutThe absolute timeout expressed in milliseconds from the beginning of the epoch (UTC).
Returns:
  • true if the wait completed before the timeout
  • false if the timeout expired before the message was fully transmitted
void outgoing_message::wait_for_completion ( ) const

Waits for the full message roundtrip - that is, for some confirmation that the message has been received and reacted upon by the target agent. After this function returns the state of the message is either abandoned, replied or rejected.

Note: This function should not be called if the intended semantics of the message is "one-way" - in this case this function would block indefinitely.

bool outgoing_message::wait_for_completion ( std::size_t  relative_timeout) const

Waits for the full message roundtrip or until the given relative timeout expires.

Parameters:
relative_timeoutThe relative timeout in milliseconds.
Returns:
  • true if the wait completed before the timeout
  • false if the timeout expired before the message was completed
bool outgoing_message::wait_for_completion_absolute ( unsigned long long  timeout) const

Waits for the full message roundtrip or until the given absolute timeout expires.

Parameters:
timeoutThe absolute timeout expressed in milliseconds from the beginning of the epoch (UTC).
Returns:
  • true if the wait completed before the timeout
  • false if the timeout expired before the message was completed
const std::vector< char > & outgoing_message::get_raw_reply ( ) const

Note: this function can be used only when the data is delivered in the raw buffer form.

parameters * outgoing_message::extract_reply ( )

The reply content is moved to the caller and the caller becomes the owner of the parameters object. This object itself is no longer holding any references to the content and therefore any future attempts to access it will result in the exception.

const std::string & outgoing_message::get_exception_msg ( ) const

This function can be called when the state of message is "rejected".

outgoing_message::outgoing_message_id outgoing_message::get_message_id ( ) const

This function can be useful together with asynchronous callbacks, the message id is the one that was returned by agent::send.