NAME

ACE_Streambuf - Create your custom streambuf by providing and ACE_*_Stream object to this template. I have tested it with ACE_SOCK_Stream and it should work fine for others as well.

SYNOPSIS

#include <ace/IOStream.h>

class ACE_Streambuf : public streambuf { public: virtual ~ACE_Streambuf (void); ACE_Time_Value *recv_timeout (ACE_Time_Value *tv = NULL); char *reset_put_buffer ( char *newBuffer = NULL, u_int _streambuf_size = 0, u_int _pptr = 0 ); u_int put_avail (void); char *reset_get_buffer ( char *newBuffer = NULL, u_int _streambuf_size = 0, u_int _gptr = 0, u_int _egptr = 0 ); u_int get_waiting (void); u_int get_avail (void); u_int streambuf_size (void); u_char timeout (void); protected: ACE_Streambuf (u_int streambuf_size, int io_mode); virtual int sync (void); virtual int underflow (void); virtual int overflow (int = EOF); void reset_base (void); char *eback_saved_; char *gptr_saved_; char *egptr_saved_; char *pbase_saved_; char *pptr_saved_; char *epptr_saved_; u_char cur_mode_; const u_char get_mode_; const u_char put_mode_; int mode_; const u_int streambuf_size_; u_char timeout_; ACE_Time_Value recv_timeout_value_; ACE_Time_Value *recv_timeout_; int syncin (void); int syncout (void); int flushbuf (void); int fillbuf (void); virtual int get_one_byte (void); virtual ssize_t send (char *buf, ssize_t len) = 0; virtual ssize_t recv ( char *buf, ssize_t len, ACE_Time_Value *tv = NULL ) = 0; virtual ssize_t recv ( char *buf, ssize_t len, int flags, ACE_Time_Value *tv = NULL ) = 0; virtual ssize_t recv_n ( char *buf, ssize_t len, int flags = 0, ACE_Time_Value *tv = NULL ) = 0; virtual ACE_HANDLE get_handle (void); inline char *base (void) const; inline int blen (void) const; inline void setb (char* b, char* eb, int a=0); inline int out_waiting (void); };

DESCRIPTION

For any iostream object, the real work is done by the underlying streambuf class. That is what we create here.

A streambuf has an internal buffer area into which data is read and written as the iostream requests and provides data. At some point during the read process, the iostream will realize that the streambuf has no more data. The underflow function of the streambuf is then called.

Likewise, during the write process, the iostream will eventually notice that the streabuf's buffer has become full and will invoke the overflow function.

The empty/full state of the read/write "buffers" are controled by two sets pointers. One set is dedicated to read, the other to write. These pointers, in turn, reference a common buffer that is to be shared by both read and write operations. It is this common buffer to which data is written and from which it is read.

The common buffer is used by functions of the streambuf as well as the iostream. Because of this and the fact that it is "shared" by both read and write operators, there is a danger of data corruption if read and write operations are allowed to take place "at the same time".

To prevent data corruption, we manipulate the read and write pointer sets so that the streambuf is in either a read-mode or write-mode at all times and can never be in both modes at the same time.

In the constructor: set the read and write sets to NULL This causes the underflow or overflow operators to be invoked at the first IO activity of the iostream.

In the underflow function we arrange for the common buffer to reference our read buffer and for the write pointer set to be disabled. If a write operation is performed by the iostream this will cause the overflow function to be invoked.

In the overflow function we arrange for the common buffer to reference our write buffer and for the read pointer set to be disabled. This causes the underflow function to be invoked when the iostream "changes our mode".

The overflow function will also invoke the send_n function to flush the buffered data to our peer. Similarly, the sync and syncout functions will cause send_n to be invoked to send the data.

Since socket's and the like do not support seeking, there can be no method for "syncing" the input. However, since we maintain separate read/write buffers, no data is lost by "syncing" the input. It simply remains buffered.

Signatures for the underflow/overflow discussed above.

virtual int underflow (void);

virtual int overflow (int = EOF);

void reset_base (void);

Two pointer sets for manipulating the read/write areas.

char *eback_saved_;

char *gptr_saved_;

char *egptr_saved_;

char *pbase_saved_;

char *pptr_saved_;

char *epptr_saved_;

With cur_mode_ we keep track of our current IO mode.

This helps us to optimize the underflow/overflow functions.
u_char cur_mode_;

const u_char get_mode_;

const u_char put_mode_;

int mode_;

const u_int streambuf_size_;

u_char timeout_;

ACE_Time_Value recv_timeout_value_;

ACE_Time_Value *recv_timeout_;

int syncin (void);

int syncout (void);

int flushbuf (void);

int fillbuf (void);

virtual int get_one_byte (void);

virtual ssize_t send (char *buf, ssize_t len) = 0;

virtual ssize_t recv (
    char *buf,
    ssize_t len,
    ACE_Time_Value *tv = NULL
    ) = 0;

virtual ssize_t recv (
    char *buf,
    ssize_t len,
    int flags,
    ACE_Time_Value *tv = NULL
    ) = 0;

virtual ssize_t recv_n (
    char *buf,
    ssize_t len,
    int flags = 0,
    ACE_Time_Value *tv = NULL
    ) = 0;

virtual ACE_HANDLE get_handle (void);

inline char *base (void) const;

inline int blen (void) const;

inline void setb (char* b, char* eb, int a=0);

inline int out_waiting (void);

AUTHOR

James CE Johnson jcej@lads.com and Jim Crossley jim@lads.com

LIBRARY

ace