Dv::Util::fdstreambuf Class Reference

A streambuf specialization that manages a file descriptor and handles timeouts. More...

#include <fdstreambuf.h>

Inheritance diagram for Dv::Util::fdstreambuf:

[legend]

Collaboration diagram for Dv::Util::fdstreambuf:

[legend]

List of all members.

Public Types
enum	{ INPUT = 0, OUTPUT = 1 }
Public Member Functions
	fdstreambuf (int fd=-1, size_t inbuf_sz=1024, size_t outbuf_sz=1024, time_t delay=0, bool non_blocking=false, unsigned int min_debug_level=5, Debugable *debug_master=0)
	This constructor simply allocates the buffers and stores the delay (in millisecs).
	fdstreambuf (int fds[], size_t inbuf_sz=1024, size_t outbuf_sz=1024, time_t delay=0, bool non_blocking_input=false, bool non_blocking_output=false, unsigned int min_debug_level=5, Debugable *debug_master=0)
	This constructor simply allocates the buffers and stores the delay (in millisecs).
virtual	~fdstreambuf ()
	This is already virtual in streambuf.
bool	shared () const
size_t	inbuf_sz () const
size_t	outbuf_sz () const
time_t	delay () const
	Return the number of millsecs to wait before an open or input operation fails.
void	delay (time_t d)
	Set delay (0 means infinite delay).
bool	non_blocking (size_t which=INPUT) const
	Return the blocking status for a file descriptor of this fdstreambuf.
int	set_non_blocking (size_t which=INPUT)
	Set non-blocking I/O for a file descriptor of this fdstreambuf.
int	fd (size_t which=INPUT) const
	Return file descriptor underlying this fdstreambuf object.
bool	fd (int i, bool non_blocking=false, size_t which=INPUT)
	Set the underlying file descriptor.
virtual bool	close (size_t which=INPUT)
	Close the underlying file descriptor.
bool	timedout () const
	Return true iff last I/O operation timed out.
bool	timedout (bool timed_out) const
	Set timedout() flag.
int	error () const
	Return last relevant errno as set by the system.
std::string	strerror () const
	Return strerror(error()), a string representation of error().
virtual int	sync ()
	Override iostream::sync(), i.e.
unsigned long long	set_n_read (unsigned long long n=0)
	Set the number bytes read so far.
unsigned long long	n_read () const
	The number of bytes read so far.
unsigned long long	set_n_written (unsigned long long n=0)
	Set the number bytes written so far.
unsigned long long	n_written () const
	The number of bytes written so far.
std::ostream &	dump (std::ostream &os) const
	Debug: write info on fdstreambuf on output stream.
Static Public Member Functions
static int	fdwait (int fd, time_t delay, int &syserrno, bool output=false, ostream_ptr *osp=0)
	Check whether input or output on a file descriptor would block.
Protected Member Functions
virtual int	underflow ()
	Override iostream::underflow(), i.e.
virtual int	overflow (int c)
	Override iostream::overflow().
int	fdwait (bool output) const
	Wait for I/O to become available.
int	fdwait (bool output, int &syserrno) const
	Wait for I/O to become available.
virtual int	iwait () const
	Wait for input to become available.
virtual int	owait () const
	Wait for output to become available.
virtual int	read (char *buf, size_t buf_sz)
	Attempt an input operation on the INPUT file descriptor.
virtual int	write (char *buf, size_t buf_sz)
	Attempt an output operation on the OUTPUT file descriptor.
virtual int	rread (char *buf, size_t len)
	Low level read function, default is read(fd(INPUT), buf, len); may set error().
virtual int	rwrite (char *buf, size_t len)
	Low level write function, default is write(fd(OUTPUT), buf, len); may set error().
void	error (int e) const
	Set error status of fdstreambuf.
Static Protected Member Functions
static int	flags (std::ios::openmode mode)
	Translate ios::openmode flags to open(2) flags like O_RDWR etc.
Private Member Functions
	fdstreambuf (const fdstreambuf &)
fdstreambuf &	operator= (const fdstreambuf &)
size_t	index (size_t which) const
	Utility that converts any parameter different from INPUT to OUTPUT.
Private Attributes
int	fds_ [2]
	Underlying file descriptors: `fds_[INPUT]` is used for input, `fds_[OUTPUT]` is used for output.
time_t	delay_
	The number of millsecs to wait before an open or input operation fails.
bool	non_blocking_ [2]
	Whether `fds_[i]` is non-blocking.
size_t	inbuf_sz_
	Size of internal input buffer.
size_t	outbuf_sz_
	Size of internal output buffer.
char *	inbuf_
	Input buffer.
char *	outbuf_
	Output buffer.
int	errno_
	Error status.
bool	timedout_
	Did the last operation time out? Set if `errno` is ETIMEDOUT.
bool	shared_
	Shared is true iff fds_[INPUT] == fds_[OUTPUT] should be maintained.
unsigned long long	n_read_
	Number of bytes read so far.
unsigned long long	n_written_
	Number of bytes written so far.

Detailed Description

A streambuf specialization that manages a file descriptor and handles timeouts.

It also supports a version that manages two filedescriptors, one for input and one for output. Derived classes should probably implement rread, rwrite, and possibly close, iwait and owait.

Definition at line 25 of file fdstreambuf.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

INPUT	index of input file descriptor
OUTPUT	index of output file descriptor

Definition at line 27 of file fdstreambuf.h.

Constructor & Destructor Documentation

Dv::Util::fdstreambuf::fdstreambuf	(	int	fd = `-1`,
		size_t	inbuf_sz = `1024`,
		size_t	outbuf_sz = `1024`,
		time_t	delay = `0`,
		bool	non_blocking = `false`,
		unsigned int	min_debug_level = `5`,
		Debugable *	debug_master = `0`
	)			`[explicit]`

This constructor simply allocates the buffers and stores the delay (in millisecs).

It uses a single file descriptor for both input and output, i.e. fd(INPUT) and fd(OUTPUT) will be identical.

Parameters:

	fd	filedescriptor to be used by this fdstreambuf
	inbuf_sz	size of input buffer.
	outbuf_sz	size of output buffer.
	delay	time, in millisecs, to wait before an open or input operation fails, a delay of 0 means ``wait foerver''.
	non_blocking	whether the underlying filedecriptor is in non-blocking (O_NONBLOCK) mode, see fctnl(2). Using a non-blocking streambuf prevents some blocking I/O operations. E.g. if select(2) indicates that writing is possible but the actual number of bytes to write is too large, the write may block indefinitely for a blocking Socket. For a non-blocking socket, the write(2) will return EAGAIN which will be handled appropriately by fdstreambuf.
	min_debug_level	if a debug_master is connected, logging info will only be written if the master's level is at least min_debug_level
	debug_master	from where debug info will be taken

See also:: Dv::DebugSlave; Dv::DebugSlave

The constructor also calls signal(SIGPIPE,SIG_IGN), causing SIGPIPE signals to be ignored. Instead, the system should let the I/O operation fail and set errno to EPIPE.

Dv::Util::fdstreambuf::fdstreambuf	(	int	fds[],
		size_t	inbuf_sz = `1024`,
		size_t	outbuf_sz = `1024`,
		time_t	delay = `0`,
		bool	non_blocking_input = `false`,
		bool	non_blocking_output = `false`,
		unsigned int	min_debug_level = `5`,
		Debugable *	debug_master = `0`
	)			`[explicit]`

This constructor simply allocates the buffers and stores the delay (in millisecs).

It uses a single file descriptor for both input and output, i.e. fd(INPUT) and fd(OUTPUT) will be identical.

The constructor also calls signal(SIGPIPE,SIG_IGN), causing SIGPIPE signals to be ignored. Instead, the system should let the I/O operation fail and set errno to EPIPE.

Example:

 int fds[2];
 if (pipe(fds) < 0)
   return error(ERROR+"pipe() failed",1);
 fdstreambuf fdsbuf(fds, 1024, 1024, 0, false, false, &std::cout);
 std::iostream os(&fdsbuf);
 os << 'a'; os.flush; // writes to pipe
 char c;
 os >> c; // read from pipe

Parameters:

	fds	filedescriptor array to be used by this fdstreambuf. The array must contain two file descriptors, `fds`[0] will be used for input operations while `fds`[1] will be used for output operations.
	inbuf_sz	size of input buffer.
	outbuf_sz	size of output buffer.
	delay	time, in millisecs, to wait before an open or input operation fails, a delay of 0 means ``wait foerver''.
	non_blocking_input	whether the underlying INPUT filedecriptor is in non-blocking (O_NONBLOCK) mode, see fctnl(2).
	non_blocking_output	whether the underlying OUTPUT filedecriptor is in non-blocking (O_NONBLOCK) mode, see fctnl(2). Using a non-blocking output file descriptor prevents some blocking I/O operations. E.g. if select(2) indicates that writing is possible but the actual number of bytes to write is too large, the write may block indefinitely for a blocking Socket. For a non-blocking socket, the write(2) will return EAGAIN which will be handled appropriately by fdstreambuf.
	min_debug_level	if a debug_master is connected, logging info will only be written if the master's level is at least min_debug_level
	debug_master	from where debug info will be taken

See also:: Dv::DebugSlave; Dv::DebugSlave

Warning:: There is no check whether fds[] has the correct size.

virtual Dv::Util::fdstreambuf::~fdstreambuf ( ) [virtual]

This is already virtual in streambuf.

Dv::Util::fdstreambuf::fdstreambuf ( const fdstreambuf & ) [private]

Member Function Documentation

bool Dv::Util::fdstreambuf::shared ( ) const [inline]

Returns:: true iff the file descriptors for INPUT and OUTPUT are identical.

Definition at line 124 of file fdstreambuf.h.

References shared_.

size_t Dv::Util::fdstreambuf::inbuf_sz ( ) const [inline]

Returns:: size of input buffer

Definition at line 127 of file fdstreambuf.h.

References inbuf_sz_.

size_t Dv::Util::fdstreambuf::outbuf_sz ( ) const [inline]

Returns:: size of output buffer

Definition at line 129 of file fdstreambuf.h.

References outbuf_sz_.

time_t Dv::Util::fdstreambuf::delay ( ) const [inline]

Return the number of millsecs to wait before an open or input operation fails.

A value of 0 means wait forever.

Returns:: The current delay value.

Definition at line 136 of file fdstreambuf.h.

References delay_.

void Dv::Util::fdstreambuf::delay ( time_t d ) [inline]

Set delay (0 means infinite delay).

Parameters:

d

delay in millisecs, 0 means ``wait forever''.

Definition at line 143 of file fdstreambuf.h.

References delay_.

bool Dv::Util::fdstreambuf::non_blocking ( size_t which = INPUT ) const [inline]

Return the blocking status for a file descriptor of this fdstreambuf.

Parameters:

which

INPUT or OUTPUT

Returns:: true iff the constructor was called with non_blocking or set_non_blocking() was called before.

Definition at line 152 of file fdstreambuf.h.

References index(), and non_blocking_.

int Dv::Util::fdstreambuf::set_non_blocking ( size_t which = INPUT )

Set non-blocking I/O for a file descriptor of this fdstreambuf.

Parameters:

which

INPUT or OUTPUT

Returns:: 0 upon success, -1 else in which case error() will reflect the system errno.

See also:: fcntl(2)

int Dv::Util::fdstreambuf::fd ( size_t which = INPUT ) const [inline]

Return file descriptor underlying this fdstreambuf object.

Parameters:

which

INPUT or OUTPUT

Returns:: The current value for the underlying file descriptor.

Definition at line 170 of file fdstreambuf.h.

References fds_, and index().

bool Dv::Util::fdstreambuf::fd	(	int	i,
		bool	non_blocking = `false`,
		size_t	which = `INPUT`
	)

Set the underlying file descriptor.

The previous descriptor, if valid, is closed.

Parameters:

	i	New file descriptor.
	non_blocking	Whether I/O should be non-blocking.
	which	File descriptor to set: INPUT or OUTPUT

Returns:: true iff close() of the previous valid file descriptor succeeded

See also:: fdstreambuf::close()

virtual bool Dv::Util::fdstreambuf::close ( size_t which = INPUT ) [virtual]

Close the underlying file descriptor.

Returns:: false iff close() of the underlying valid file descriptor failed.

bool Dv::Util::fdstreambuf::timedout ( ) const [inline]

Return true iff last I/O operation timed out.

Returns:: true iff the last I/O operation timed out or timedout(true) was called since the last I/O operation.

Definition at line 199 of file fdstreambuf.h.

References timedout_.

bool Dv::Util::fdstreambuf::timedout ( bool timed_out ) const

Set timedout() flag.

This flag can only be cleared explicitly by fdstreambuf::timedout(false) or by fdstreambuf::fd(int).

Parameters:

timed_out

New value for timedout().

Returns:: true iff timedout status actually changed. It will return false, e.g. if the argument is false but the previous timedout status was not true.

int Dv::Util::fdstreambuf::error ( ) const [inline]

Return last relevant errno as set by the system.

Returns:: The last relevant errno as set by the system.

Definition at line 217 of file fdstreambuf.h.

References errno_.

std::string Dv::Util::fdstreambuf::strerror ( ) const

Return strerror(error()), a string representation of error().

Returns:: A string representation of error().

static int Dv::Util::fdstreambuf::fdwait	(	int	fd,
		time_t	delay,
		int &	syserrno,
		bool	output = `false`,
		ostream_ptr *	osp = `0`
	)			`[static]`

Check whether input or output on a file descriptor would block.

Parameters:

	fd	file descriptor to check, none if -1
	delay	time (in millisecs) we are prepared to wait. If `0`, `fdwait()` may block indefinitely.
	syserrno	will contain system's errno if return -1
	output	false if fd is checked for input
	osp	if not 0, pointer to Dv::ostream_ptr on which trace/debug output will be written

Returns:: 1 if input/output is available; 0 if a timeout occurred (in which case syserrno=ETIMEOUT) and a value <0 if another error occurred, in which case syserrno set to errno.

See also:: Dv::ostream_ptr

Referenced by owait().

virtual int Dv::Util::fdstreambuf::sync ( ) [virtual]

Override iostream::sync(), i.e.

force all pending output to be written using fdstreambuf::rwrite().

Returns:: 0 if ok, -1 else.

unsigned long long Dv::Util::fdstreambuf::set_n_read ( unsigned long long n = 0 )

Set the number bytes read so far.

The constructors set this number to 0.

Parameters:

n new value of n_read

Returns:: the old value of n_read

See also:: Dv::Util::fdstreambuf::n_read

unsigned long long Dv::Util::fdstreambuf::n_read ( ) const [inline]

The number of bytes read so far.

Returns:: number of bytes read so far or since the last call to Dv:Util::set_n_read

See also:: Dv::Util::fdstreambuf::set_n_read

Definition at line 266 of file fdstreambuf.h.

References n_read_.

unsigned long long Dv::Util::fdstreambuf::set_n_written ( unsigned long long n = 0 )

Set the number bytes written so far.

The constructors set this number to 0.

Parameters:

n new value of n_written

Returns:: the old value of n_written

See also:: Dv::Util::fdstreambuf::n_written

unsigned long long Dv::Util::fdstreambuf::n_written ( ) const [inline]

The number of bytes written so far.

Returns:: number of bytes written so far or since the last call to Dv:Util::set_n_written

See also:: Dv::Util::fdstreambuf::set_n_written

Definition at line 281 of file fdstreambuf.h.

References n_written_.

std::ostream& Dv::Util::fdstreambuf::dump ( std::ostream & os ) const

Debug: write info on fdstreambuf on output stream.

Parameters:

os

write dump to this stream

Returns:: os

virtual int Dv::Util::fdstreambuf::underflow ( ) [protected, virtual]

Override iostream::underflow(), i.e.

attempt to fill the input buffer using fdstreambuf::rread().

Returns:: next input char or EOF.

virtual int Dv::Util::fdstreambuf::overflow ( int c ) [protected, virtual]

Override iostream::overflow().

May call fdstreambuf::sync().

Returns:: c if the character was succeffuly written or EOF.

int Dv::Util::fdstreambuf::fdwait ( bool output ) const [protected]

Wait for I/O to become available.

Wait for output or input, depending on the value of the parameter. Sets error() appropriately if return value is not 1.

Parameters:

output

Wait for output to be available if

Returns:: 1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).

See also:: fdwait

int Dv::Util::fdstreambuf::fdwait	(	bool	output,
		int &	syserrno
	)			const `[protected]`

Wait for I/O to become available.

Wait for output or input, depending on the value of the parameter.

Parameters:

	output	Wait for output to be available if
	syserrno	System errorno (output variable).

Returns:: 1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).

See also:: fdwait

virtual int Dv::Util::fdstreambuf::iwait ( ) const [protected, virtual]

Wait for input to become available.

Equivalent to fdwait(false). This is a virtual function because for some transports, iwait() may need to consult other data structures. E.g. when using openssl, iwait should call SSL_pending before fdstreambuf::iwait. This is the function actually used in the implementation of fdstreambuf::read.

Returns:: 1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).

virtual int Dv::Util::fdstreambuf::owait ( ) const [inline, protected, virtual]

Wait for output to become available.

Equivalent to fdwait(true).

Returns:: 1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).

Definition at line 348 of file fdstreambuf.h.

References fdwait().

virtual int Dv::Util::fdstreambuf::read	(	char *	buf,
		size_t	buf_sz
	)			`[protected, virtual]`

Attempt an input operation on the INPUT file descriptor.

Parameters:

	buf	Buffer where characters read will be put.
	buf_sz	Number of characters to read.

Returns:: number of chars read, 0 on EOF, -1 if timeout, -2 if other error.

On timeout, error() is set to ETIMEDOUT. Input operations are retried if they were interrupted.

See also:: error()

virtual int Dv::Util::fdstreambuf::write	(	char *	buf,
		size_t	buf_sz
	)			`[protected, virtual]`

Attempt an output operation on the OUTPUT file descriptor.

Parameters:

	buf	Buffer containing characters to write.
	buf_sz	Number of characters to write from buf.

Returns:: number of chars written, 0 on EOF, -1 if timeout, -2 if other error. On timeout, error() is set to ETIMEDOUT. Output operations are retried if they were interrupted.

See also:: error()

virtual int Dv::Util::fdstreambuf::rread	(	char *	buf,
		size_t	len
	)			`[protected, virtual]`

Low level read function, default is read(fd(INPUT), buf, len); may set error().

Derived classes can override this function.

Parameters:

	buf	Buffer where characters read will be put.
	len	Number of characters to read.

Returns:: number of chars read, 0 on EOF, -1 on error.

See also:: error()

virtual int Dv::Util::fdstreambuf::rwrite	(	char *	buf,
		size_t	len
	)			`[protected, virtual]`

Low level write function, default is write(fd(OUTPUT), buf, len); may set error().

Derived classes can override this function.

Parameters:

	buf	Buffer containing characters to write.
	len	Number of characters to write from buf.

Returns:: number of chars read, 0 means no chars were written. On error, -1 is returned.

See also:: error()

static int Dv::Util::fdstreambuf::flags ( std::ios::openmode mode ) [static, protected]

Translate ios::openmode flags to open(2) flags like O_RDWR etc.

Parameters:

mode

Stream open mode.

Returns:: A combination of O_RDWR, O_CREAT, O_APPEND, O_WRONLY, O_TRUNC, O_RDONLY.

Currently, the function understands combinations with ios::in, ios::out, ios::app, ios::trunc.

void Dv::Util::fdstreambuf::error ( int e ) const [protected]

Set error status of fdstreambuf.

Parameters:

e

new error code.

See also:: fdstreambuf::error().

fdstreambuf& Dv::Util::fdstreambuf::operator= ( const fdstreambuf & ) [private]

size_t Dv::Util::fdstreambuf::index ( size_t which ) const [inline, private]

Utility that converts any parameter different from INPUT to OUTPUT.

Parameters:

which

size_t, normally INPUT or OUTPUT

Returns:: INPUT if paramater is INPUT; OUTPUT if parameter is not INPUT

Definition at line 436 of file fdstreambuf.h.

References INPUT, and OUTPUT.

Referenced by fd(), and non_blocking().

Member Data Documentation

int Dv::Util::fdstreambuf::fds_[2] [private]

Underlying file descriptors: fds_[INPUT] is used for input, fds_[OUTPUT] is used for output.

It is possible that fds_[INPUT] == fds_[OUTPUT]. A negative value indicates no file descriptor available.

Definition at line 444 of file fdstreambuf.h.

Referenced by fd().

time_t Dv::Util::fdstreambuf::delay_ [private]

The number of millsecs to wait before an open or input operation fails.

A value of 0 means wait forever.

Definition at line 450 of file fdstreambuf.h.

Referenced by delay().

bool Dv::Util::fdstreambuf::non_blocking_[2] [private]

Whether fds_[i] is non-blocking.

Definition at line 455 of file fdstreambuf.h.

Referenced by non_blocking().

size_t Dv::Util::fdstreambuf::inbuf_sz_ [private]

Size of internal input buffer.

Definition at line 460 of file fdstreambuf.h.

Referenced by inbuf_sz().

size_t Dv::Util::fdstreambuf::outbuf_sz_ [private]

Size of internal output buffer.

Definition at line 464 of file fdstreambuf.h.

Referenced by outbuf_sz().

char* Dv::Util::fdstreambuf::inbuf_ [private]

Input buffer.

Definition at line 468 of file fdstreambuf.h.

char* Dv::Util::fdstreambuf::outbuf_ [private]

Output buffer.

Definition at line 472 of file fdstreambuf.h.

int Dv::Util::fdstreambuf::errno_ [mutable, private]

Error status.

A value of 0 means ok. Usually, the value of the last errno as set by the system.

Definition at line 477 of file fdstreambuf.h.

Referenced by error().

bool Dv::Util::fdstreambuf::timedout_ [mutable, private]

Did the last operation time out? Set if errno is ETIMEDOUT.

See also:: timedout

Definition at line 482 of file fdstreambuf.h.

Referenced by timedout().

bool Dv::Util::fdstreambuf::shared_ [private]

Shared is true iff fds_[INPUT] == fds_[OUTPUT] should be maintained.

Definition at line 487 of file fdstreambuf.h.

Referenced by shared().

unsigned long long Dv::Util::fdstreambuf::n_read_ [private]

Number of bytes read so far.

Can be set by the user as well.

Definition at line 490 of file fdstreambuf.h.

Referenced by n_read().

unsigned long long Dv::Util::fdstreambuf::n_written_ [private]

Number of bytes written so far.

Can be set by the user as well.

Definition at line 492 of file fdstreambuf.h.

Referenced by n_written().

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

fdstreambuf.h

Dv::Util::fdstreambuf Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation