#include <MessageChannel.h>
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.
Be careful with mixing the sending/receiving of array messages, scalar messages and file descriptors. If you send a collection of any of these in a specific order, then the receiving side must receive them in the exact some order. So suppose you first send a message, then a file descriptor, then a scalar, then the receiving side must first receive a message, then a file descriptor, then a scalar. If the receiving side does things in the wrong order then bad things will happen.
MessageChannel is not thread-safe, but is reentrant.
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. | |
void | close () |
Close 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 char *name,...) |
Send an array message, which consists of the given strings, over the underlying file descriptor. | |
void | writeScalar (const string &str) |
Send a scalar message over the underlying file descriptor. | |
void | writeScalar (const char *data, unsigned int size) |
Send a scalar message over the underlying file descriptor. | |
void | writeRaw (const char *data, unsigned int size) |
Send a block of data over the underlying file descriptor. | |
void | writeRaw (const string &data) |
Send a block of data over the underlying file descriptor. | |
void | writeFileDescriptor (int fileDescriptor) |
Pass a file descriptor. | |
bool | read (vector< string > &args) |
Read an array message from the underlying file descriptor. | |
bool | readScalar (string &output) |
Read a scalar message from the underlying file descriptor. | |
bool | readRaw (void *buf, unsigned int size) |
Read exactly size bytes of data from the underlying file descriptor, and put the result in buf . | |
int | readFileDescriptor () |
Receive a file descriptor, which had been passed over the underlying 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 |
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 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::writeScalar | ( | const string & | str | ) | [inline] |
Send a scalar message over 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::writeScalar | ( | const char * | data, | |
unsigned int | size | |||
) | [inline] |
Send a scalar message over 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::writeRaw | ( | const char * | data, | |
unsigned int | size | |||
) | [inline] |
Send a block of data over the underlying file descriptor.
This method blocks until everything is sent.
data | The data to send. | |
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::writeRaw | ( | const string & | data | ) | [inline] |
Send a block of data over the underlying file descriptor.
This method blocks until everything is sent.
data | The data to send. |
data != NULL
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
void Passenger::MessageChannel::writeFileDescriptor | ( | int | fileDescriptor | ) | [inline] |
Pass a file descriptor.
This only works if the underlying file descriptor is a Unix socket.
fileDescriptor | The file descriptor to pass. |
SystemException | Something went wrong during file descriptor passing. | |
boost::thread_interrupted |
fileDescriptor >= 0
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 |
bool Passenger::MessageChannel::readScalar | ( | string & | output | ) | [inline] |
Read a scalar message from the underlying file descriptor.
output | The message will be put in here. |
SystemException | An error occured while writing the data to the file descriptor. | |
boost::thread_interrupted |
bool Passenger::MessageChannel::readRaw | ( | void * | buf, | |
unsigned int | size | |||
) | [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. |
SystemException | Something went wrong during reading. | |
boost::thread_interrupted |
int Passenger::MessageChannel::readFileDescriptor | ( | ) | [inline] |
Receive a file descriptor, which had been passed over the underlying file descriptor.
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 |