blocxx
BLOCXX_NAMESPACE::UnnamedPipe Class Referenceabstract

Abstract interface for an UnnamedPipe. More...

#include <UnnamedPipe.hpp>

Inheritance diagram for BLOCXX_NAMESPACE::UnnamedPipe:
BLOCXX_NAMESPACE::IOIFC BLOCXX_NAMESPACE::IntrusiveCountableBase BLOCXX_NAMESPACE::PosixUnnamedPipe

Public Types

enum  EBlockingMode { E_NONBLOCKING , E_BLOCKING }
 
enum  EOpen { E_DONT_OPEN , E_OPEN }
 
- Public Types inherited from BLOCXX_NAMESPACE::IOIFC
enum  ErrorAction { E_THROW_ON_ERROR , E_RETURN_ON_ERROR }
 

Public Member Functions

virtual ~UnnamedPipe ()
 
int writeInt (int value)
 Write an int (native binary representation) to the pipe.
 
int writeString (const String &strData)
 Writes a String to the pipe.
 
int readInt (int *value)
 Reads an int (native binary representation) from the pipe.
 
int readString (String &strData)
 Reads a String from the pipe.
 
void setReadTimeout (const Timeout &timeout)
 Sets the read timeout value.
 
BLOCXX_DEPRECATED void setReadTimeout (int seconds)
 
Timeout getReadTimeout ()
 Gets the read timeout value.
 
void setWriteTimeout (const Timeout &timeout)
 Sets the write timeout value.
 
BLOCXX_DEPRECATED void setWriteTimeout (int seconds)
 
Timeout getWriteTimeout ()
 Gets the write timeout value.
 
void setTimeouts (const Timeout &timeout)
 Sets the read & write timeout values.
 
BLOCXX_DEPRECATED void setTimeouts (int seconds)
 
String readAll ()
 Read from the pipe and collect into a string, until the other end of the pipe is closed.
 
virtual void open ()=0
 Open the pipe.
 
virtual int close ()=0
 Close the pipe.
 
virtual bool isOpen () const =0
 Is the pipe open or closed?
 
virtual Select_t getReadSelectObj () const =0
 Get the read select object.
 
virtual Select_t getWriteSelectObj () const =0
 Get the write select object.
 
virtual void setBlocking (EBlockingMode isBlocking=E_BLOCKING)=0
 Set the pipe's blocking mode.
 
virtual void setWriteBlocking (EBlockingMode isBlocking=E_BLOCKING)=0
 Set blocking mode for writing to pipe.
 
virtual void setReadBlocking (EBlockingMode isBlocking=E_BLOCKING)=0
 Set blocking mode for reading from pipe.
 
virtual EBlockingMode getReadBlocking () const =0
 Get the current blocking mode for reading from pipe.
 
virtual EBlockingMode getWriteBlocking () const =0
 Get the current blocking mode for writing from pipe.
 
virtual Descriptor getInputDescriptor () const =0
 Get the underlying input descriptor.
 
virtual Descriptor getOutputDescriptor () const =0
 Get the underlying output descriptor.
 
virtual void passDescriptor (Descriptor h, const UnnamedPipeRef &ackPipe=0, const ProcessRef &targetProcess=0)=0
 Sends a Descriptor to the peer.
 
virtual AutoDescriptor receiveDescriptor (const UnnamedPipeRef &ackPipe=0)=0
 Gets a Descriptor from the peer.
 
virtual int closeInputHandle ()=0
 
virtual int closeOutputHandle ()=0
 
- Public Member Functions inherited from BLOCXX_NAMESPACE::IOIFC
virtual ~IOIFC ()
 
virtual int read (void *dataIn, int dataInLen, ErrorAction errorAsException=E_RETURN_ON_ERROR)=0
 Read a specified number of bytes from the device that is exposing the IOIFC interface.
 
virtual int write (const void *dataOut, int dataOutLen, ErrorAction errorAsException=E_RETURN_ON_ERROR)=0
 Write a specified number of bytes to the device that is exposing the IOIFC interface.
 

Static Public Member Functions

static UnnamedPipeRef createUnnamedPipe (EOpen doOpen=E_OPEN)
 Create an instance of the concrete class that implements the UnnamedPipe interface.
 
static UnnamedPipeRef createUnnamedPipeFromDescriptor (AutoDescriptor inputAndOutput)
 Create an instance of the concrete class that implements the UnnamedPipe interface connected bidirectionally to the specified descriptor.
 
static UnnamedPipeRef createUnnamedPipeFromDescriptor (AutoDescriptor input, AutoDescriptor output)
 Create an instance of the concrete class that implements the UnnamedPipe interface connected to the specified descriptors.
 
static void createConnectedPipes (UnnamedPipeRef &first, UnnamedPipeRef &second)
 Create a connected pair of pipes.
 
static UnnamedPipeRef createStdin ()
 Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdin.
 
static UnnamedPipeRef createStdout ()
 Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdout.
 
static UnnamedPipeRef createStdinStdout ()
 Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdin and stdout.
 
static UnnamedPipeRef createStderr ()
 Create an instance of the concrete class that implements the UnnamedPipe interface connected to stderr.
 

Static Public Attributes

static const int INFINITE_TIMEOUT = -1
 

Protected Member Functions

 UnnamedPipe ()
 
- Protected Member Functions inherited from BLOCXX_NAMESPACE::IntrusiveCountableBase
 IntrusiveCountableBase ()
 
 IntrusiveCountableBase (const IntrusiveCountableBase &)
 
IntrusiveCountableBaseoperator= (const IntrusiveCountableBase &)
 
virtual ~IntrusiveCountableBase ()
 

Private Attributes

Timeout m_readTimeout
 
Timeout m_writeTimeout
 

Detailed Description

Abstract interface for an UnnamedPipe.

Blocking is enabled by default.

Definition at line 60 of file UnnamedPipe.hpp.

Member Enumeration Documentation

◆ EBlockingMode

Enumerator
E_NONBLOCKING 
E_BLOCKING 

Definition at line 192 of file UnnamedPipe.hpp.

◆ EOpen

Enumerator
E_DONT_OPEN 
E_OPEN 

Definition at line 263 of file UnnamedPipe.hpp.

Constructor & Destructor Documentation

◆ ~UnnamedPipe()

BLOCXX_NAMESPACE::UnnamedPipe::~UnnamedPipe ( )
virtual

Definition at line 65 of file UnnamedPipe.cpp.

◆ UnnamedPipe()

BLOCXX_NAMESPACE::UnnamedPipe::UnnamedPipe ( )
inlineprotected

Definition at line 331 of file UnnamedPipe.hpp.

Member Function Documentation

◆ close()

virtual int BLOCXX_NAMESPACE::UnnamedPipe::close ( )
pure virtual

Close the pipe.

Returns
-1 on error, 0 on success.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ closeInputHandle()

virtual int BLOCXX_NAMESPACE::UnnamedPipe::closeInputHandle ( )
pure virtual

◆ closeOutputHandle()

virtual int BLOCXX_NAMESPACE::UnnamedPipe::closeOutputHandle ( )
pure virtual

◆ createConnectedPipes()

void BLOCXX_NAMESPACE::UnnamedPipe::createConnectedPipes ( UnnamedPipeRef & first,
UnnamedPipeRef & second )
static

Create a connected pair of pipes.

The input from first will be connected to the output of second, and the input from second will be connected to the output of first. The pipes default to have 10 minute timeouts.

Parameters
firstThe first pipe.
secondThe second pipe.
Exceptions
UnnamedPipeExceptionwith error code EMFILE if too many descriptors are in use by the process.

Definition at line 244 of file UnnamedPipe.cpp.

References BLOCXX_THROW_ERRNO_MSG, and createUnnamedPipeFromDescriptor().

◆ createStderr()

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createStderr ( )
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected to stderr.

Returns
Reference to the UnnamedPipe object.

Definition at line 198 of file UnnamedPipe.cpp.

References BLOCXX_INVALID_HANDLE, BLOCXX_THROW_ERRNO_MSG, and BLOCXX_NAMESPACE::AutoResource< Policy >::get().

◆ createStdin()

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createStdin ( )
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdin.

Returns
Reference to the UnnamedPipe object.

Definition at line 142 of file UnnamedPipe.cpp.

References BLOCXX_INVALID_HANDLE, BLOCXX_THROW_ERRNO_MSG, and BLOCXX_NAMESPACE::AutoResource< Policy >::get().

◆ createStdinStdout()

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createStdinStdout ( )
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdin and stdout.

Returns
Reference to the UnnamedPipe object.

Definition at line 176 of file UnnamedPipe.cpp.

References BLOCXX_INVALID_HANDLE, BLOCXX_THROW_ERRNO_MSG, and BLOCXX_NAMESPACE::AutoResource< Policy >::get().

◆ createStdout()

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createStdout ( )
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected to stdout.

Returns
Reference to the UnnamedPipe object.

Definition at line 159 of file UnnamedPipe.cpp.

References BLOCXX_INVALID_HANDLE, BLOCXX_THROW_ERRNO_MSG, and BLOCXX_NAMESPACE::AutoResource< Policy >::get().

◆ createUnnamedPipe()

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createUnnamedPipe ( EOpen doOpen = E_OPEN)
static

Create an instance of the concrete class that implements the UnnamedPipe interface.

The input and output of the pipe will be connected. The pipe defaults to have 10 minute timeouts.

Parameters
doOpenOpen the pipe or not.

Definition at line 130 of file UnnamedPipe.cpp.

Referenced by BLOCXX_NAMESPACE::Socket::createShutDownMechanism(), and BLOCXX_NAMESPACE::PosixExec::spawnImpl().

◆ createUnnamedPipeFromDescriptor() [1/2]

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createUnnamedPipeFromDescriptor ( AutoDescriptor input,
AutoDescriptor output )
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected to the specified descriptors.

Parameters
inputThe input descriptor to connect.
outputThe output descriptor to connect.
Returns
Reference to the UnnamedPipe object.

Definition at line 232 of file UnnamedPipe.cpp.

◆ createUnnamedPipeFromDescriptor() [2/2]

UnnamedPipeRef BLOCXX_NAMESPACE::UnnamedPipe::createUnnamedPipeFromDescriptor ( AutoDescriptor inputAndOutput)
static

Create an instance of the concrete class that implements the UnnamedPipe interface connected bidirectionally to the specified descriptor.

Parameters
inputAndOutputThe input and output descriptor to connect.
Returns
Reference to the UnnamedPipe object.

Definition at line 215 of file UnnamedPipe.cpp.

References BLOCXX_INVALID_HANDLE, BLOCXX_THROW_ERRNO_MSG, and BLOCXX_NAMESPACE::AutoResource< Policy >::get().

Referenced by createConnectedPipes().

◆ getInputDescriptor()

virtual Descriptor BLOCXX_NAMESPACE::UnnamedPipe::getInputDescriptor ( ) const
pure virtual

Get the underlying input descriptor.

The UnnamedPipe instance retains ownership of the descriptor.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

Referenced by BLOCXX_NAMESPACE::Exec::PreExec::closePipesOnExec(), and BLOCXX_NAMESPACE::PosixUnnamedPipe::passDescriptor().

◆ getOutputDescriptor()

virtual Descriptor BLOCXX_NAMESPACE::UnnamedPipe::getOutputDescriptor ( ) const
pure virtual

Get the underlying output descriptor.

The UnnamedPipe instance retains ownership of the descriptor.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

Referenced by BLOCXX_NAMESPACE::Exec::PreExec::closePipesOnExec(), and BLOCXX_NAMESPACE::PosixUnnamedPipe::receiveDescriptor().

◆ getReadBlocking()

virtual EBlockingMode BLOCXX_NAMESPACE::UnnamedPipe::getReadBlocking ( ) const
pure virtual

Get the current blocking mode for reading from pipe.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ getReadSelectObj()

virtual Select_t BLOCXX_NAMESPACE::UnnamedPipe::getReadSelectObj ( ) const
pure virtual

Get the read select object.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ getReadTimeout()

Timeout BLOCXX_NAMESPACE::UnnamedPipe::getReadTimeout ( )
inline

Gets the read timeout value.

If blocking is enabled this is the number of seconds a read operation will block. Exception safety: No-throw

Returns
The read timeout.

Definition at line 126 of file UnnamedPipe.hpp.

Referenced by BLOCXX_NAMESPACE::PosixUnnamedPipe::read(), and BLOCXX_NAMESPACE::PosixUnnamedPipe::receiveDescriptor().

◆ getWriteBlocking()

virtual EBlockingMode BLOCXX_NAMESPACE::UnnamedPipe::getWriteBlocking ( ) const
pure virtual

Get the current blocking mode for writing from pipe.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ getWriteSelectObj()

virtual Select_t BLOCXX_NAMESPACE::UnnamedPipe::getWriteSelectObj ( ) const
pure virtual

Get the write select object.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ getWriteTimeout()

Timeout BLOCXX_NAMESPACE::UnnamedPipe::getWriteTimeout ( )
inline

Gets the write timeout value.

If blocking is enabled this is the number of seconds a write operation will block. Exception safety: No-throw

Returns
The write timeout.

Definition at line 143 of file UnnamedPipe.hpp.

Referenced by BLOCXX_NAMESPACE::PosixUnnamedPipe::passDescriptor(), and BLOCXX_NAMESPACE::PosixUnnamedPipe::write().

◆ isOpen()

virtual bool BLOCXX_NAMESPACE::UnnamedPipe::isOpen ( ) const
pure virtual

Is the pipe open or closed?

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ open()

virtual void BLOCXX_NAMESPACE::UnnamedPipe::open ( )
pure virtual

Open the pipe.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ passDescriptor()

virtual void BLOCXX_NAMESPACE::UnnamedPipe::passDescriptor ( Descriptor h,
const UnnamedPipeRef & ackPipe = 0,
const ProcessRef & targetProcess = 0 )
pure virtual

Sends a Descriptor to the peer.

Parameters
hThe Descriptor to send.
Exceptions
IOExceptionon I/O error.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ readAll()

String BLOCXX_NAMESPACE::UnnamedPipe::readAll ( )

Read from the pipe and collect into a string, until the other end of the pipe is closed.

Exception safety: Strong for the C++ instance. Fubared for the pipe. If an exception is thrown, the pipe won't be reset to it's pre-call state.

Returns
The string with collected data.
Exceptions
IOExceptionon error

Definition at line 113 of file UnnamedPipe.cpp.

References BLOCXX_NAMESPACE::IOIFC::E_THROW_ON_ERROR, BLOCXX_NAMESPACE::IOIFC::read(), and BLOCXX_NAMESPACE::StringBuffer::releaseString().

◆ readInt()

int BLOCXX_NAMESPACE::UnnamedPipe::readInt ( int * value)

Reads an int (native binary representation) from the pipe.

If blocking is enabled, readInt() will block for up to getReadTimeout() seconds or forever if getReadTimeout() == -1. Exception safety: No-throw

Parameters
valueOut parameter where the read int will be stored.
Returns
The number of bytes read, -1 on error, ETIMEDOUT on timeout.

Definition at line 88 of file UnnamedPipe.cpp.

References BLOCXX_NAMESPACE::IOIFC::read().

Referenced by readString().

◆ readString()

int BLOCXX_NAMESPACE::UnnamedPipe::readString ( String & strData)

Reads a String from the pipe.

If blocking is enabled, readInt() will block for up to getReadTimeout() seconds or forever if getReadTimeout() == -1. Exception safety: Strong for the C++ instance. Fubared for the pipe. If an exception is thrown, the pipe won't be reset to it's pre-call state.

Parameters
strDataOut parameter where the read int will be stored.
Returns
The number of bytes read, -1 on error, ETIMEDOUT on timeout.
Exceptions
std::bad_alloc

Definition at line 94 of file UnnamedPipe.cpp.

References BLOCXX_NAMESPACE::String::E_TAKE_OWNERSHIP, BLOCXX_NAMESPACE::AutoPtrVec< X >::get(), BLOCXX_NAMESPACE::IOIFC::read(), readInt(), and BLOCXX_NAMESPACE::AutoPtrVec< X >::release().

◆ receiveDescriptor()

virtual AutoDescriptor BLOCXX_NAMESPACE::UnnamedPipe::receiveDescriptor ( const UnnamedPipeRef & ackPipe = 0)
pure virtual

Gets a Descriptor from the peer.

Returns
The Descriptor sent by the peer.
Exceptions
IOExceptionon I/O error or if the peer does not send a Descriptor

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ setBlocking()

virtual void BLOCXX_NAMESPACE::UnnamedPipe::setBlocking ( EBlockingMode isBlocking = E_BLOCKING)
pure virtual

Set the pipe's blocking mode.

Precondition: The pipe is open.

Parameters
isBlockingnew blocking mode.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ setReadBlocking()

virtual void BLOCXX_NAMESPACE::UnnamedPipe::setReadBlocking ( EBlockingMode isBlocking = E_BLOCKING)
pure virtual

Set blocking mode for reading from pipe.

Precondition: The pipe input is open.

Parameters
isBlockingnew read blocking mode.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ setReadTimeout() [1/2]

void BLOCXX_NAMESPACE::UnnamedPipe::setReadTimeout ( const Timeout & timeout)
inline

Sets the read timeout value.

If blocking is enabled this is the number of seconds a read operation will block. Exception safety: No-throw

Parameters
timeoutThe new read timeout.

Definition at line 117 of file UnnamedPipe.hpp.

Referenced by BLOCXX_NAMESPACE::PosixExec::spawnImpl().

◆ setReadTimeout() [2/2]

BLOCXX_DEPRECATED void BLOCXX_NAMESPACE::UnnamedPipe::setReadTimeout ( int seconds)
inline

Definition at line 118 of file UnnamedPipe.hpp.

◆ setTimeouts() [1/2]

void BLOCXX_NAMESPACE::UnnamedPipe::setTimeouts ( const Timeout & timeout)
inline

Sets the read & write timeout values.

If blocking is enabled this is the number of seconds a read or write operation will block. Exception safety: No-throw

Parameters
timeoutThe new timeout.

Definition at line 151 of file UnnamedPipe.hpp.

Referenced by BLOCXX_NAMESPACE::PosixUnnamedPipe::PosixUnnamedPipe(), and BLOCXX_NAMESPACE::PosixUnnamedPipe::PosixUnnamedPipe().

◆ setTimeouts() [2/2]

BLOCXX_DEPRECATED void BLOCXX_NAMESPACE::UnnamedPipe::setTimeouts ( int seconds)
inline

Definition at line 152 of file UnnamedPipe.hpp.

◆ setWriteBlocking()

virtual void BLOCXX_NAMESPACE::UnnamedPipe::setWriteBlocking ( EBlockingMode isBlocking = E_BLOCKING)
pure virtual

Set blocking mode for writing to pipe.

Precondition: The pipe output is open.

Parameters
isBlockingnew write blocking mode.

Implemented in BLOCXX_NAMESPACE::PosixUnnamedPipe.

◆ setWriteTimeout() [1/2]

void BLOCXX_NAMESPACE::UnnamedPipe::setWriteTimeout ( const Timeout & timeout)
inline

Sets the write timeout value.

If blocking is enabled this is the number of seconds a write operation will block. Exception safety: No-throw

Parameters
timeoutThe new write timeout.

Definition at line 134 of file UnnamedPipe.hpp.

◆ setWriteTimeout() [2/2]

BLOCXX_DEPRECATED void BLOCXX_NAMESPACE::UnnamedPipe::setWriteTimeout ( int seconds)
inline

Definition at line 135 of file UnnamedPipe.hpp.

◆ writeInt()

int BLOCXX_NAMESPACE::UnnamedPipe::writeInt ( int value)

Write an int (native binary representation) to the pipe.

If blocking is enabled, writeInt() will block for up to getWriteTimeout() seconds or forever if getWriteTimeout() == -1. Exception safety: No-throw

Parameters
valueThe value to write.
Returns
The number of bytes written, -1 on error, ETIMEDOUT on timeout.

Definition at line 70 of file UnnamedPipe.cpp.

References BLOCXX_NAMESPACE::IOIFC::write().

Referenced by writeString().

◆ writeString()

int BLOCXX_NAMESPACE::UnnamedPipe::writeString ( const String & strData)

Writes a String to the pipe.

This should be read from the other side by readString. If blocking is enabled, writeString() will block for up to getWriteTimeout() seconds or forever if getWriteTimeout() == -1. Exception safety: No-throw

Parameters
strDataThe String to write.
Returns
The number of bytes written, -1 on error, ETIMEDOUT on timeout.

Definition at line 76 of file UnnamedPipe.cpp.

References BLOCXX_NAMESPACE::String::c_str(), BLOCXX_NAMESPACE::String::length(), BLOCXX_NAMESPACE::IOIFC::write(), and writeInt().

Member Data Documentation

◆ INFINITE_TIMEOUT

const int BLOCXX_NAMESPACE::UnnamedPipe::INFINITE_TIMEOUT = -1
static

Definition at line 109 of file UnnamedPipe.hpp.

◆ m_readTimeout

Timeout BLOCXX_NAMESPACE::UnnamedPipe::m_readTimeout
private

Definition at line 336 of file UnnamedPipe.hpp.

◆ m_writeTimeout

Timeout BLOCXX_NAMESPACE::UnnamedPipe::m_writeTimeout
private

Definition at line 337 of file UnnamedPipe.hpp.


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