Passenger::MessageChannel Class Reference
[Apache-independent support classes and function]

Convenience class for I/O operations on file descriptors. More...

#include <MessageChannel.h>

List of all members.

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.

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,...)

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.

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.

Detailed Description

Convenience class for I/O operations on file descriptors.

This class provides convenience methods for:

sending and receiving raw data over a file descriptor.
sending and receiving messages over a file descriptor.
file descriptor passing over a Unix socket. All of these methods use exceptions for error reporting.

There are two kinds of messages:

Array messages. These are just a list of strings, and the message itself has a specific length. The contained strings may not contain NUL characters ('\0'). Note that an array message must have at least one element.
Scalar messages. These are byte strings which may contain arbitrary binary data. Scalar messages also have a specific length. The protocol is designed to be low overhead, easy to implement and easy to parse.

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.

Note:

I/O operations are not buffered.

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.

Constructor & Destructor Documentation

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.

Member Function Documentation

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.

Exceptions:

	SystemException
	boost::thread_interrupted

bool Passenger::MessageChannel::read ( vector< string > & args ) [inline]

Read an array message from the underlying file descriptor.

Parameters:

args

The message will be put in this variable.

Returns:: Whether end-of-file has been reached. If so, then the contents of args will be undefined.

Exceptions:

	SystemException	If an error occured while receiving the message.
	boost::thread_interrupted

See also:: write()

int Passenger::MessageChannel::readFileDescriptor ( ) [inline]

Receive a file descriptor, which had been passed over the underlying file descriptor.

Returns:: The passed file descriptor.

Exceptions:

	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
	)			`[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.

Parameters:

	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.

Returns:: Whether reading was successful or whether EOF was reached.

Precondition:: buf != NULL

Exceptions:

	SystemException	Something went wrong during reading.
	boost::thread_interrupted

See also:: writeRaw()

bool Passenger::MessageChannel::readScalar ( string & output ) [inline]

Read a scalar message from the underlying file descriptor.

Parameters:

output

The message will be put in here.

Returns:: Whether end-of-file was reached during reading.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

See also:: writeScalar()

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.

Parameters:

msec

The timeout, in milliseconds. If 0 is given, there will be no timeout.

Exceptions:

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.

Parameters:

msec

The timeout, in milliseconds. If 0 is given, there will be no timeout.

Exceptions:

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.

Parameters:

	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.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

Precondition:: None of the message elements may contain a NUL character ('\0').

See also:: read(), write(const list<string> &)

void Passenger::MessageChannel::write ( const vector< string > & args ) [inline]

Send an array message, which consists of the given elements, over the underlying file descriptor.

Parameters:

args

The message elements.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

Precondition:: None of the message elements may contain a NUL character ('\0').

See also:: read(), write(const char *, ...)

void Passenger::MessageChannel::write ( const list< string > & args ) [inline]

Send an array message, which consists of the given elements, over the underlying file descriptor.

Parameters:

args

The message elements.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

Precondition:: None of the message elements may contain a NUL character ('\0').

See also:: read(), write(const char *, ...)

template<typename StringArrayType , typename StringArrayConstIteratorType >

void Passenger::MessageChannel::write ( const StringArrayType & args ) [inline]

Send an array message, which consists of the given elements, over the underlying file descriptor.

Parameters:

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.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

Precondition:: None of the message elements may contain a NUL character ('\0').

See also:: read(), write(const char *, ...)

void Passenger::MessageChannel::writeFileDescriptor ( int fileDescriptor ) [inline]

Pass a file descriptor.

This only works if the underlying file descriptor is a Unix socket.

Parameters:

fileDescriptor

The file descriptor to pass.

Exceptions:

	SystemException	Something went wrong during file descriptor passing.
	boost::thread_interrupted

Precondition:: fileDescriptor >= 0

See also:: readFileDescriptor()

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.

Parameters:

data

The data to send.

Precondition:: data != NULL

Exceptions:

	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.

Parameters:

	data	The data to send.
	size	The number of bytes in `data`.

Precondition:: data != NULL

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

See also:: readRaw()

void Passenger::MessageChannel::writeScalar	(	const char *	data,
		unsigned int	size
	)			`[inline]`

Send a scalar message over the underlying file descriptor.

Parameters:

	data	The scalar message's content.
	size	The number of bytes in `data`.

Precondition:: data != NULL

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

See also:: readScalar(), writeScalar(const string &)

void Passenger::MessageChannel::writeScalar ( const string & str ) [inline]

Send a scalar message over the underlying file descriptor.

Parameters:

str

The scalar message's content.

Exceptions:

	SystemException	An error occured while writing the data to the file descriptor.
	boost::thread_interrupted

See also:: readScalar(), writeScalar(const char *, unsigned int)

The documentation for this class was generated from the following file:

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.
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,...)
	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.
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.

Passenger::MessageChannel Class Reference [Apache-independent support classes and function]

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Passenger::MessageChannel Class Reference
[Apache-independent support classes and function]