cosmos::Pipe Class Reference

Creates a unidirectional pipe communication channel. More...

#include <Pipe.hxx>

Public Member Functions
	Pipe ()
	Creates a pipe with both ends stored in the object.
void	closeReadEnd ()
void	closeWriteEnd ()
FileDescriptor	readEnd ()
FileDescriptor	writeEnd ()
bool	haveReadEnd () const
bool	haveWriteEnd () const
FileDescriptor	takeReadEndOwnership ()
	Return the read end, passing ownership to the caller.
FileDescriptor	takeWriteEndOwnership ()
	Return the write end, passing ownership to the caller.

Static Public Member Functions
static size_t	maxAtomicWriteSize ()
	Maximum number of bytes that can be transmitted over a Pipe as a single message.

Protected Member Functions
void	invalidateReadEnd ()
void	invalidateWriteEnd ()

Protected Attributes
FileDescriptor	m_read_end
FileDescriptor	m_write_end

Static Protected Attributes
static const size_t	MAX_ATOMIC_WRITE = PIPE_BUF

Detailed Description

Creates a unidirectional pipe communication channel.

A pipe consists of two file descriptors, one for reading and one for writing to. To make use of it, one end needs to be inherited to a child process or otherwise be used e.g. as a wakeup mechanism for select() calls etc.

When using a pipe to communicate between processes an important aspect is that all write ends need to be closed before an end-of-file is reported on the read end. Therefore you need to make sure that only the necessary part of the pipe is inherited to the child process to communicate with.

The pipe file descriptors created by this class have the close-on-exec flag set by default, so you need to explicitly re-enable that flag to inherit the necessary end to a child process.

Definition at line 27 of file Pipe.hxx.

Constructor & Destructor Documentation

Pipe()

cosmos::Pipe::Pipe ( )

explicit

Creates a pipe with both ends stored in the object.

Definition at line 13 of file Pipe.cxx.

           {
        int ends[2];
        if (::pipe2(ends, O_CLOEXEC | O_DIRECT) != 0) {
                cosmos_throw (ApiError("pipe2()"));
        }
 
        m_read_end.setFD(FileNum{ends[0]});
        m_write_end.setFD(FileNum{ends[1]});
}

~Pipe()

cosmos::Pipe::~Pipe ( )

inline

Definition at line 37 of file Pipe.hxx.

{ closeReadEnd(); closeWriteEnd(); }

Member Function Documentation

closeReadEnd()

void cosmos::Pipe::closeReadEnd ( )

inline

Definition at line 39 of file Pipe.hxx.

{ if (haveReadEnd()) m_read_end.close(); }

closeWriteEnd()

void cosmos::Pipe::closeWriteEnd ( )

inline

Definition at line 40 of file Pipe.hxx.

{ if (haveWriteEnd()) m_write_end.close(); }

haveReadEnd()

bool cosmos::Pipe::haveReadEnd ( ) const

inline

Definition at line 45 of file Pipe.hxx.

{ return m_read_end.valid(); }

haveWriteEnd()

bool cosmos::Pipe::haveWriteEnd ( ) const

inline

Definition at line 46 of file Pipe.hxx.

{ return m_write_end.valid(); }

invalidateReadEnd()

void cosmos::Pipe::invalidateReadEnd ( )

inlineprotected

Definition at line 81 of file Pipe.hxx.

{ m_read_end.reset(); }

invalidateWriteEnd()

void cosmos::Pipe::invalidateWriteEnd ( )

inlineprotected

Definition at line 82 of file Pipe.hxx.

{ m_write_end.reset(); }

maxAtomicWriteSize()

static size_t cosmos::Pipe::maxAtomicWriteSize ( )

inlinestatic

Maximum number of bytes that can be transmitted over a Pipe as a single message.

A pipe can maintain messages boundaries i.e. each write is returned in the same length on the read end. This is only possible up to a maximum size, however. This function returns this size.

Definition at line 75 of file Pipe.hxx.

                                           {
                return MAX_ATOMIC_WRITE;
        }

readEnd()

FileDescriptor cosmos::Pipe::readEnd ( )

inline

Definition at line 42 of file Pipe.hxx.

{ return m_read_end; }

takeReadEndOwnership()

FileDescriptor cosmos::Pipe::takeReadEndOwnership ( )

inline

Return the read end, passing ownership to the caller.

the read end descriptor stored in the object will be invalidated and not be accessible at a later time anymore.

Definition at line 53 of file Pipe.hxx.

                                              {
                auto ret = readEnd();
                invalidateReadEnd();
                return ret;
        }

takeWriteEndOwnership()

FileDescriptor cosmos::Pipe::takeWriteEndOwnership ( )

inline

Return the write end, passing ownership to the caller.

See also

takeReadEndOwnership()

Definition at line 63 of file Pipe.hxx.

                                               {
                auto ret = writeEnd();
                invalidateWriteEnd();
                return ret;
        }

writeEnd()

FileDescriptor cosmos::Pipe::writeEnd ( )

inline

Definition at line 43 of file Pipe.hxx.

{ return m_write_end; }

Member Data Documentation

m_read_end

FileDescriptor cosmos::Pipe::m_read_end

protected

Definition at line 86 of file Pipe.hxx.

m_write_end

FileDescriptor cosmos::Pipe::m_write_end

protected

Definition at line 87 of file Pipe.hxx.

MAX_ATOMIC_WRITE

const size_t cosmos::Pipe::MAX_ATOMIC_WRITE = PIPE_BUF

staticprotected

Definition at line 88 of file Pipe.hxx.

---

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

• include/io/Pipe.hxx
• src/io/Pipe.cxx