<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="class.eventbufferevent" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>The EventBufferEvent class</title>
 <titleabbrev>EventBufferEvent</titleabbrev>
 <partintro>
<!-- {{{ EventBufferEvent intro -->
  <section xml:id="eventbufferevent.intro">
   &reftitle.intro;
   <para>
    Represents Libevent&apos;s buffer event.
   </para>
   <para>
    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:
   </para>
   <orderedlist>
    <listitem>
     <para>
      Decide that we want to write some data to a connection; put that data in
      a buffer.
     </para>
    </listitem>
    <listitem>
     <para>
      Wait for the connection to become writable
     </para>
    </listitem>
    <listitem>
     <para>
      Write as much of the data as we can
     </para>
    </listitem>
    <listitem>
     <para>
      Remember how much we wrote, and if we still have more data to write,
      wait for the connection to become writable again.
     </para>
    </listitem>
   </orderedlist>
   <para>
    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.
   </para>
  </section>
<!-- }}} -->
  <section xml:id="eventbufferevent.synopsis">
   &reftitle.classsynopsis;

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass>
     <classname>EventBufferEvent</classname>
    </ooclass>
<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <modifier>final</modifier>
      <classname>EventBufferEvent</classname>
     </ooclass>
    </classsynopsisinfo>
<!-- }}} -->
    <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.reading">EventBufferEvent::READING</varname>
     <initializer>1</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.writing">EventBufferEvent::WRITING</varname>
     <initializer>2</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.eof">EventBufferEvent::EOF</varname>
     <initializer>16</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.error">EventBufferEvent::ERROR</varname>
     <initializer>32</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.timeout">EventBufferEvent::TIMEOUT</varname>
     <initializer>64</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.connected">EventBufferEvent::CONNECTED</varname>
     <initializer>128</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.opt-close-on-free">EventBufferEvent::OPT_CLOSE_ON_FREE</varname>
     <initializer>1</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.opt-threadsafe">EventBufferEvent::OPT_THREADSAFE</varname>
     <initializer>2</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.opt-defer-callbacks">EventBufferEvent::OPT_DEFER_CALLBACKS</varname>
     <initializer>4</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.opt-unlock-callbacks">EventBufferEvent::OPT_UNLOCK_CALLBACKS</varname>
     <initializer>8</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.ssl-open">EventBufferEvent::SSL_OPEN</varname>
     <initializer>0</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.ssl-connecting">EventBufferEvent::SSL_CONNECTING</varname>
     <initializer>1</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.constants.ssl-accepting">EventBufferEvent::SSL_ACCEPTING</varname>
     <initializer>2</initializer>
    </fieldsynopsis>
    <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>public</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.props.fd">fd</varname>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>public</modifier>
     <type>int</type>
     <varname linkend="eventbufferevent.props.priority">priority</varname>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>public</modifier>
     <modifier>readonly</modifier>
     <type>EventBuffer</type>
     <varname linkend="eventbufferevent.props.input">input</varname>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>public</modifier>
     <modifier>readonly</modifier>
     <type>EventBuffer</type>
     <varname linkend="eventbufferevent.props.output">output</varname>
    </fieldsynopsis>
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.eventbufferevent')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
   </classsynopsis>
<!-- }}} -->
  </section>
<!-- {{{ EventBufferEvent properties -->
  <section xml:id="eventbufferevent.props">
   &reftitle.properties;
   <variablelist>
    <varlistentry xml:id="eventbufferevent.props.fd">
     <term>
      <varname>fd</varname>
     </term>
     <listitem>
      <para>
       Numeric file descriptor associated with the buffer event. Normally
       represents a bound socket. Equals to &null;, if there is no file
       descriptor(socket) associated with the buffer event.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.props.priority">
     <term>
      <varname>priority</varname>
     </term>
     <listitem>
      <para>
       The priority of the events used to implement the buffer event.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.props.input">
     <term>
      <varname>input</varname>
     </term>
     <listitem>
      <para>
       Underlying input buffer object(
       <classname>EventBuffer</classname>)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.props.output">
     <term>
      <varname>output</varname>
     </term>
     <listitem>
      <para>
       Underlying output buffer object(
       <classname>EventBuffer</classname>)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
<!-- }}} -->
<!-- {{{ EventBufferEvent constants -->
  <section xml:id="eventbufferevent.constants">
   &reftitle.constants;
   <variablelist>
    <varlistentry xml:id="eventbufferevent.constants.reading">
     <term>
      <constant>EventBufferEvent::READING</constant>
     </term>
     <listitem>
      <para>
       An event occurred during a read operation on the bufferevent. See the
       other flags for which event it was.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.writing">
     <term>
      <constant>EventBufferEvent::WRITING</constant>
     </term>
     <listitem>
      <para>
       An event occurred during a write operation on the bufferevent. See the
       other flags for which event it was.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.eof">
     <term>
      <constant>EventBufferEvent::EOF</constant>
     </term>
     <listitem>
      <para>
       Got an end-of-file indication on the buffer event.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.error">
     <term>
      <constant>EventBufferEvent::ERROR</constant>
     </term>
     <listitem>
      <para>
       An error occurred during a bufferevent operation. For more information
       on what the error was, call
       <methodname>EventUtil::getLastSocketErrno</methodname>
       and/or
       <methodname>EventUtil::getLastSocketError</methodname>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.timeout">
     <term>
      <constant>EventBufferEvent::TIMEOUT</constant>
     </term>
     <listitem>
      <para></para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.connected">
     <term>
      <constant>EventBufferEvent::CONNECTED</constant>
     </term>
     <listitem>
      <para>
       Finished a requested connection on the bufferevent.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.opt-close-on-free">
     <term>
      <constant>EventBufferEvent::OPT_CLOSE_ON_FREE</constant>
     </term>
     <listitem>
      <para>
       When the buffer event is freed, close the underlying transport. This
       will close an underlying socket, free an underlying buffer event, etc.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.opt-threadsafe">
     <term>
      <constant>EventBufferEvent::OPT_THREADSAFE</constant>
     </term>
     <listitem>
      <para>
       Automatically allocate locks for the bufferevent, so that it’s safe
       to use from multiple threads.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.opt-defer-callbacks">
     <term>
      <constant>EventBufferEvent::OPT_DEFER_CALLBACKS</constant>
     </term>
     <listitem>
      <para>
       When this flag is set, the bufferevent defers all of its callbacks. See
       <link
      xlink:href="http://www.wangafu.net/~nickm/libevent-book/Ref6_bufferevent.html#_deferred_callbacks">Fast
      portable non-blocking network programming with Libevent, Deferred callbacks</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.opt-unlock-callbacks">
     <term>
      <constant>EventBufferEvent::OPT_UNLOCK_CALLBACKS</constant>
     </term>
     <listitem>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.ssl-open">
     <term>
      <constant>EventBufferEvent::SSL_OPEN</constant>
     </term>
     <listitem>
      <para>
       The SSL handshake is done
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.ssl-connecting">
     <term>
      <constant>EventBufferEvent::SSL_CONNECTING</constant>
     </term>
     <listitem>
      <para>
       SSL is currently performing negotiation as a client
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="eventbufferevent.constants.ssl-accepting">
     <term>
      <constant>EventBufferEvent::SSL_ACCEPTING</constant>
     </term>
     <listitem>
      <para>
       SSL is currently performing negotiation as a server
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
<!-- }}} -->
 </partintro>

 &reference.event.entities.eventbufferevent;

</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->