Convenience class for I/O operations on file descriptors. More...
#include <MessageChannel.h>
Public Member Functions | |
MessageChannel () | |
Construct a new MessageChannel with no underlying file descriptor. | |
MessageChannel (int fd) | |
Construct a new MessageChannel with the given file descriptor. | |
int | filenum () const |
Returns the underlying file descriptor. | |
bool | connected () const |
Returns whether close() has been called. | |
void | close () |
Close the underlying file descriptor. | |
template<typename StringArrayType , typename StringArrayConstIteratorType > | |
void | write (const StringArrayType &args) |
Send an array message, which consists of the given elements, over the underlying file descriptor. | |
void | write (const list< string > &args) |
Send an array message, which consists of the given elements, over the underlying file descriptor. | |
void | write (const vector< string > &args) |
Send an array message, which consists of the given elements, over the underlying file descriptor. | |
void | write (const char *name, va_list &ap) |
Send an array message, which consists of the given strings, over the underlying file descriptor. | |
void | write (const char *name,...) |
Send an array message, which consists of the given strings, over the underlying file descriptor. | |
void | writeUint32 (unsigned int value) |
Write a 32-bit big-endian unsigned integer to the underlying file descriptor. | |
void | writeScalar (const string &str) |
Write a scalar message to the underlying file descriptor. | |
void | writeScalar (const char *data, unsigned int size) |
Write a scalar message to the underlying file descriptor. | |
void | writeFileDescriptor (int fileDescriptor, bool negotiate=true) |
Pass a file descriptor. | |
bool | read (vector< string > &args) |
Read an array message from the underlying file descriptor. | |
bool | readUint32 (unsigned int &value, unsigned long long *timeout=NULL) |
Read a 32-bit big-endian unsigned integer from the underlying file descriptor. | |
bool | readScalar (string &output, unsigned int maxSize=0, unsigned long long *timeout=NULL) |
Read a scalar message from the underlying file descriptor. | |
bool | readRaw (void *buf, unsigned int size, unsigned long long *timeout=NULL) |
Read exactly size bytes of data from the underlying file descriptor, and put the result in buf . | |
int | readFileDescriptor (bool negotiate=true) |
Receive a file descriptor, which had been passed over the underlying file descriptor. | |
void | setReadTimeout (unsigned int msec) |
Set the timeout value for reading data from this channel. | |
void | setWriteTimeout (unsigned int msec) |
Set the timeout value for writing data to this channel. |
Convenience class for I/O operations on file descriptors.
This class provides convenience methods for:
There are two kinds of messages:
'\0'
). Note that an array message must have at least one element.MessageChannel is to be wrapped around a file descriptor. For example:
int p[2]; pipe(p); MessageChannel channel1(p[0]); MessageChannel channel2(p[1]); // Send an array message. channel2.write("hello", "world !!", NULL); list<string> args; channel1.read(args); // args now contains { "hello", "world !!" } // Send a scalar message. channel2.writeScalar("some long string which can contain arbitrary binary data"); string str; channel1.readScalar(str);
The life time of a MessageChannel is independent from that of the wrapped file descriptor. If a MessageChannel object is destroyed, the file descriptor is not automatically closed. Call close() if you want to close the file descriptor.
Passenger::MessageChannel::MessageChannel | ( | ) | [inline] |
Construct a new MessageChannel with no underlying file descriptor.
Thus the resulting MessageChannel object will not be usable. This constructor exists to allow one to declare an "empty" MessageChannel variable which is to be initialized later.
void Passenger::MessageChannel::close | ( | ) | [inline] |
Close the underlying file descriptor.
If this method is called multiple times, the file descriptor will only be closed the first time.
SystemException | ||
boost::thread_interrupted |
int Passenger::MessageChannel::filenum | ( | ) | const [inline] |
Returns the underlying file descriptor.
-1 if it has already been closed.
bool Passenger::MessageChannel::read | ( | vector< string > & | args | ) | [inline] |
Read an array message from the underlying file descriptor.
args | The message will be put in this variable. |
args
will be undefined. SystemException | If an error occured while receiving the message. | |
boost::thread_interrupted |
int Passenger::MessageChannel::readFileDescriptor | ( | bool | negotiate = true |
) | [inline] |
Receive a file descriptor, which had been passed over the underlying file descriptor.
negotiate | See Ruby's MessageChannel::send_io method's comments. |
SystemException | If something went wrong during the receiving of a file descriptor. Perhaps the underlying file descriptor isn't a Unix socket. | |
IOException | Whatever was received doesn't seem to be a file descriptor. | |
boost::thread_interrupted |
bool Passenger::MessageChannel::readRaw | ( | void * | buf, | |
unsigned int | size, | |||
unsigned long long * | timeout = NULL | |||
) | [inline] |
Read exactly size
bytes of data from the underlying file descriptor, and put the result in buf
.
If end-of-file has been reached, or if end-of-file was encountered before size
bytes have been read, then false
will be returned. Otherwise (i.e. if the read was successful), true
will be returned.
buf | The buffer to place the read data in. This buffer must be at least size bytes long. | |
size | The number of bytes to read. | |
timeout | A pointer to an integer, which specifies the maximum number of milliseconds that may be spent on reading the size bytes of data. If the timeout expired then TimeoutException will be thrown. If this function returns without throwing an exception, then the total number of milliseconds spent on reading will be deducted from timeout . Pass NULL if you do not want to enforce a timeout. |
SystemException | Something went wrong during reading. | |
TimeoutException | Unable to read size bytes of data within timeout milliseconds. | |
boost::thread_interrupted |
bool Passenger::MessageChannel::readScalar | ( | string & | output, | |
unsigned int | maxSize = 0 , |
|||
unsigned long long * | timeout = NULL | |||
) | [inline] |
Read a scalar message from the underlying file descriptor.
output | The message will be put in here. | |
maxSize | The maximum number of bytes that may be read. If the scalar to read is larger than this, then a SecurityException will be thrown. Set to 0 for no size limit. | |
timeout | A pointer to an integer, representing the maximum number of milliseconds to spend on reading the entire scalar. A TimeoutException will be thrown if unable to read the entire scalar within this time period. If no exception is thrown, the the amount of time spent on waiting will be deducted from *timeout . Pass NULL if you do not want to enforce any time limits. |
SystemException | An error occured while reading data from the file descriptor. | |
SecurityException | There is more data to read than allowed by maxSize. | |
TimeoutException | Unable to read the entire scalar within timeout milliseconds. | |
boost::thread_interrupted |
bool Passenger::MessageChannel::readUint32 | ( | unsigned int & | value, | |
unsigned long long * | timeout = NULL | |||
) | [inline] |
Read a 32-bit big-endian unsigned integer from the underlying file descriptor.
value | Upon success, the read value will be stored in here. | |
timeout | A pointer to an integer, representing the maximum number of milliseconds to spend on reading the entire integer. A TimeoutException will be thrown if the timeout expires. If no exception is thrown, the the amount of time spent on waiting will be deducted from *timeout . Pass NULL if you do not want to enforce any time limits. |
SystemException | An error occurred while reading data from the file descriptor. | |
boost::thread_interrupted |
void Passenger::MessageChannel::setReadTimeout | ( | unsigned int | msec | ) | [inline] |
Set the timeout value for reading data from this channel.
If no data can be read within the timeout period, then a SystemException will be thrown by one of the read methods, with error code EAGAIN or EWOULDBLOCK.
msec | The timeout, in milliseconds. If 0 is given, there will be no timeout. |
SystemException | Cannot set the timeout. |
void Passenger::MessageChannel::setWriteTimeout | ( | unsigned int | msec | ) | [inline] |
Set the timeout value for writing data to this channel.
If no data can be written within the timeout period, then a SystemException will be thrown, with error code EAGAIN or EWOULDBLOCK.
msec | The timeout, in milliseconds. If 0 is given, there will be no timeout. |
SystemException | Cannot set the timeout. |
void Passenger::MessageChannel::write | ( | const char * | name, | |
... | ||||
) | [inline] |
Send an array message, which consists of the given strings, over the underlying file descriptor.
name | The first element of the message to send. | |
... | Other elements of the message. These *must* be strings, i.e. of type char*. It is also required to terminate this list with a NULL. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
'\0'
). void Passenger::MessageChannel::write | ( | const char * | name, | |
va_list & | ap | |||
) | [inline] |
Send an array message, which consists of the given strings, over the underlying file descriptor.
Like write(const char *name, ...)
but takes a va_list instead.
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
'\0'
). void Passenger::MessageChannel::write | ( | const vector< string > & | args | ) | [inline] |
Send an array message, which consists of the given elements, over the underlying file descriptor.
args | The message elements. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
'\0'
). void Passenger::MessageChannel::write | ( | const list< string > & | args | ) | [inline] |
Send an array message, which consists of the given elements, over the underlying file descriptor.
args | The message elements. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
'\0'
). void Passenger::MessageChannel::write | ( | const StringArrayType & | args | ) | [inline] |
Send an array message, which consists of the given elements, over the underlying file descriptor.
args | An object which contains the message elements. This object must support STL-style iteration, and each iterator must have an std::string as value. Use the StringArrayType and StringArrayConstIteratorType template parameters to specify the exact type names. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
'\0'
). void Passenger::MessageChannel::writeFileDescriptor | ( | int | fileDescriptor, | |
bool | negotiate = true | |||
) | [inline] |
Pass a file descriptor.
This only works if the underlying file descriptor is a Unix socket.
fileDescriptor | The file descriptor to pass. | |
negotiate | See Ruby's MessageChannel::send_io method's comments. |
SystemException | Something went wrong during file descriptor passing. | |
boost::thread_interrupted |
fileDescriptor >= 0
void Passenger::MessageChannel::writeScalar | ( | const char * | data, | |
unsigned int | size | |||
) | [inline] |
Write a scalar message to the underlying file descriptor.
data | The scalar message's content. | |
size | The number of bytes in data . |
data != NULL
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
void Passenger::MessageChannel::writeScalar | ( | const string & | str | ) | [inline] |
Write a scalar message to the underlying file descriptor.
str | The scalar message's content. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
void Passenger::MessageChannel::writeUint32 | ( | unsigned int | value | ) | [inline] |
Write a 32-bit big-endian unsigned integer to the underlying file descriptor.
SystemException | An error occurred while writing the data to the file descriptor. | |
boost::thread_interrupted |