--- name: "ACE_Streambuf" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Streambuf" --- # ACE\_Streambuf(3) 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. ## 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 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); ``` The overflow function receives the character which caused the overflow. ``` void reset_base (void); ``` Resets the base pointer and streambuf mode. This is used internally when get/put buffers are allocatd. ## 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_; ``` mode tells us if we're working for an istream, ostream, or iostream. ``` const u_int streambuf_size_; ``` This defines the size of the input and output buffers. It can be set by the object constructor. ``` u_char timeout_; ``` Did we take an error because of an IO operation timeout? ``` ACE_Time_Value recv_timeout_value_; ``` ``` ACE_Time_Value *recv_timeout_; ``` We want to allow the user to provide Time\_Value pointers to prevent infinite blocking while waiting to receive data. ``` int syncin (void); ``` syncin is called when the input needs to be synced with the source file. In a filebuf, this results in the seek system call being used. We can't do that on socket-like connections, so this does basically nothing. That's safe because we have a separate read buffer to maintain the already-read data. In a filebuf, the single common buffer is used forcing the seek call. ``` int syncout (void); ``` syncout is called when the output needs to be flushed. This is easily done by calling the peer's send\_n function. ``` int flushbuf (void); ``` flushbuf is the worker of syncout. It is a separate function because it gets used sometimes in different context. ``` int fillbuf (void); ``` fillbuf is called in a couple of places. This is the worker of underflow. It will attempt to fill the read buffer from the peer. ``` virtual int get_one_byte (void); ``` Used by fillbuf and others to get exactly one byte from the peer. recv\_n is used to be sure we block until something is available. It is virtual because we really need to override it for datagram-derived objects. ``` 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; ``` Stream connections and "unconnected connections" (ie -- datagrams) need to work just a little differently. We derive custom Streambuf objects for them and provide these functions at that time. ``` 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