The EventBufferEvent class

Introduction

Usually an application wants to perform some amount of data buffering in
addition to just responding to events. When we want to write data, for
example, the usual pattern looks like:

Decide that we want to write some data to a connection; put that data in
a buffer.

Wait for the connection to become writable

Write as much of the data as we can

Remember how much we wrote, and if we still have more data to write,
wait for the connection to become writable again.

This buffered I/O pattern is common enough that Libevent provides a
generic mechanism for it. A "buffer event" consists of an underlying
transport (like a socket), a read buffer, and a write buffer. Instead of
regular events, which give callbacks when the underlying transport is
ready to be read or written, a buffer event invokes its user-supplied
callbacks when it has read or written enough data.

By default, when the bufferevent is set up to be threadsafe, the buffer
event’s locks are held whenever the any user-provided callback is
invoked. Setting this option makes Libevent release the buffer
event’s lock when it’s invoking the callbacks.