balb::PipeControlChannel Class Reference

#include <balb_pipecontrolchannel.h>

Detailed Description

This class is a mechanism for reading control messages from a named pipe. Use start to spawn a thread that handles messages arriving at the pipe, and shutdown to stop reading. stop blocks until the processing thread has been terminated by a call to shutdown (either before stop is called, or from some other thread).

See balb_pipecontrolchannel

Public Types
typedef bsl::function< void(const bslstl::StringRef &message)>	ControlCallback

Public Member Functions
	PipeControlChannel (const ControlCallback &callback, bslma::Allocator *basicAllocator=0)
	PipeControlChannel (const ControlCallback &callback, int permissions, bslma::Allocator *basicAllocator=0)
	~PipeControlChannel ()
void	setPermissions (int permissions)
int	start (const char *pipeName)
template<class STRING_TYPE >
int	start (const STRING_TYPE &pipeName)
int	start (const char *pipeName, const bslmt::ThreadAttributes &attributes)
template<class STRING_TYPE >
int	start (const STRING_TYPE &pipeName, const bslmt::ThreadAttributes &attributes)
void	shutdown ()
void	stop ()
int	permissions () const
const bsl::string &	pipeName () const
bslma::Allocator *	allocator () const

Static Public Attributes
static const int	k_DEFAULT_PERMISSIONS

Member Typedef Documentation

ControlCallback

typedef bsl::function<void(const bslstl::StringRef& message)> balb::PipeControlChannel::ControlCallback

This type of function is called to handle control messages received on the pipe. The message is one complete message read from the pipe, without the terminating newline character.

Constructor & Destructor Documentation

PipeControlChannel() [1/2]

balb::PipeControlChannel::PipeControlChannel ( const ControlCallback &  callback, bslma::Allocator *  basicAllocator = 0  )

explicit

Create a pipe control mechanism that dispatches messages to the specified callback. Optionally specify basicAllocator to supply memory. If basicAllocator is zero, the currently installed default allocator is used. The permission bit mask of the underlying named pipe defaults to k_DEFAULT_PERMISSIONS (0666, i.e., read/write for everyone) and may be changed by calling setPermissions before start.

PipeControlChannel() [2/2]

balb::PipeControlChannel::PipeControlChannel	(	const ControlCallback &	callback,
		int	permissions,
		bslma::Allocator *	basicAllocator = 0
	)

Create a pipe control mechanism that dispatches messages to the specified callback and creates its underlying named pipe with the specified permissions bit mask. Optionally specify basicAllocator to supply memory. If basicAllocator is zero, the currently installed default allocator is used.

Precondition

The behavior is undefined unless bdls::FilePermissions::isValidBaseBits(permissions) (i.e., unless permissions is a combination of the nine owner/group/others read/write/execute bits defined by bdls::FilePermissions; note that k_SET_UID, k_SET_GID, and k_STICKY_BIT are not accepted). On operating systems that do not support Unix-style permission bits (notably Windows) the value is ignored and falls back to the operating-system default (see the component-level documentation for details).

~PipeControlChannel()

balb::PipeControlChannel::~PipeControlChannel

(

)

Destroy this object. Shut down the processing thread if it is still running and block until it terminates. Close the named pipe and clean up any associated system resources.

Member Function Documentation

allocator()

bslma::Allocator * balb::PipeControlChannel::allocator ( ) const

inline

Return the allocator used by this object to supply memory.

Note

Note that if no allocator was supplied at construction the default allocator in effect at construction is used.

permissions()

int balb::PipeControlChannel::permissions ( ) const

inline

Return the permission bit mask that will be applied to the named pipe on the next call to start.

pipeName()

const bsl::string & balb::PipeControlChannel::pipeName ( ) const

inline

Return the fully qualified system name of the pipe.

setPermissions()

void balb::PipeControlChannel::setPermissions

(

int

permissions

)

Set the permission bit mask for the underlying named pipe to the specified permissions value.

Precondition

The behavior is undefined unless bdls::FilePermissions::isValidBaseBits(permissions). This setting only takes effect on the next call to start; calling this method has no effect on a pipe that has already been opened. See the class-level documentation for a description of the cross-platform semantics.

The behavior is undefined if this method is called while the background thread is running (i.e., after start and before shutdown), or if the permissions value is not valid.

shutdown()

void balb::PipeControlChannel::shutdown

(

)

Stop reading from the pipe and dispatching messages. If the background thread has begun processing a message, this method will block until a message that is currently being processed completes.

start() [1/4]

int balb::PipeControlChannel::start

(

const char *

pipeName

)

Open a named pipe having the specified pipeName, and start a thread to read messages and dispatch them to the callback specified at construction. Optionally specify attributes of the background processing thread. If attributes is not supplied, a default constructed ThreadAttributes object will be used. Return 0 on success, and a non-zero value otherwise. In particular, return a non-zero value if the pipe cannot be opened or if it is detected that another process is reading from the pipe. pipeName must be of the types const char *, char *, bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

start() [2/4]

int balb::PipeControlChannel::start	(	const char *	pipeName,
		const bslmt::ThreadAttributes &	attributes
	)

start() [3/4]

template<class STRING_TYPE >

int balb::PipeControlChannel::start

(

const STRING_TYPE &

pipeName

)

start() [4/4]

template<class STRING_TYPE >

int balb::PipeControlChannel::start	(	const STRING_TYPE &	pipeName,
		const bslmt::ThreadAttributes &	attributes
	)

stop()

void balb::PipeControlChannel::stop

(

)

Block until the background thread has been terminated by a call to shutdown. Then close the pipe and clean up the associated file.

Member Data Documentation

d_handle

void* balb::PipeControlChannel::d_handle

d_readFd

int balb::PipeControlChannel::d_readFd

[struct]

struct { ... } balb::PipeControlChannel::d_unix

[struct]

struct { ... } balb::PipeControlChannel::d_windows

d_writeFd

int balb::PipeControlChannel::d_writeFd

k_DEFAULT_PERMISSIONS

const int balb::PipeControlChannel::k_DEFAULT_PERMISSIONS

static

Initial value:

=
                                         bdls::FilePermissions::k_OWNER_READ  |
                                         bdls::FilePermissions::k_OWNER_WRITE |
                                         bdls::FilePermissions::k_GROUP_READ  |
                                         bdls::FilePermissions::k_GROUP_WRITE |
                                         bdls::FilePermissions::k_OTHERS_READ |
                                         bdls::FilePermissions::k_OTHERS_WRITE

The default permission bit mask for the underlying named pipe (read/write for owner, group, and others).

---

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

• balb_pipecontrolchannel.h