php-doc-en/reference/mysqlnd_mux/concepts.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<chapter xml:id="mysqlnd-mux.concepts" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Concepts</title>
 <para>
  This explains the architecture and related concepts for this plugin.
  Reading and understanding these concepts is required to successfully
  use this plugin.
 </para>

 <section xml:id="mysqlnd-mux.architecture">
  <title>Architecture</title>
  <para>
   The mysqlnd connection multiplexing plugin is implemented as a PHP extension.
   It is written in C and operates under the hood of PHP. During the
   startup of the PHP interpreter, in the module initialization phase of the
   PHP engine, it gets registered as a
   <link linkend="book.mysqlnd">mysqlnd</link> plugin to replace specific
   mysqlnd C methods.
  </para>
  <para>
   The mysqlnd library uses PHP streams to communicate with the MySQL
   server. PHP streams are accessed by the mysqlnd library through its net module.
   The mysqlnd connection multiplexing plugin proxies methods of the mysqlnd
   library net module to control opening and closing of network streams.
  </para>
  <para>
   Upon opening a user connection to MySQL using the appropriate connection
   functions of either  <link linkend="book.mysqli">mysqli</link>,
   <link linkend="ref.pdo-mysql">PDO_MYSQL</link> or
   <link linkend="book.mysql">ext/mysql</link>, the plugin will search its
   connection pool for an open network connection. If the pool
   contains a network connection to the host specified by the connect function
   using the transport method requested (TCP/IP, Unix domain socket, Windows named pipe),
   the pooled connection is linked to the user handle. Otherwise, a new
   network connection is opened, put into the poolm and associated with the
   user connection handle. This way, multiple user handles can be linked
   to the same network connection.
  </para>
 </section>

 <section xml:id="mysqlnd-mux.connection_pool">
  <title>Connection pool</title>
  <para>
   The plugins connection pool is created when PHP initializes its modules
   (<literal>MINIT</literal>) and free'd when PHP shuts down the modules
   (<literal>MSHUTDOWN</literal>). This is the same as for persistent MySQL connections.
  </para>
  <para>
   Depending on the deployment model, the pool is used for the duration of one
   or multiple web requests. Network connections are bound to the lifespan
   of an operating system level process. If the PHP process serves multiple
   web requests as it is the case for Fast-CGI or threaded web server deployments,
   then the pooled connections can be reused over multiple connections.
   Because multiplexing means sharing connections, it can even happen with a
   threaded deployment that two threads or two distinct web requests are
   linked to one pooled network connections.
  </para>
  <para>
   A pooled connection is explicitly closed once the last reference to it
   is released. An implicit close happens when PHP shuts down its modules.
  </para>
 </section>

 <section xml:id="mysqlnd-mux.sharing_connections">
  <title>Sharing connections</title>
  <para>
   The PHP mysqlnd connection multiplexing plugin changes the relationship
   between a users connection handle and the underlying MySQL connection.
   Without the plugin, every MySQL connection belongs to exactly one
   user connection at a time. The multiplexing plugin changes.
   A MySQL connection is shared among multiple user handles.
   There no one-to-one relation if using the plugin.
  </para>
  <para>
   Sharing pooled connections has an impact on the connection state.
   State changing operations from multiple user handles pointing to one
   MySQL connection are not isolated from each other. If, for example,
   a session variable is set through one user connection handle,
   the session variable becomes visible to all other user handles that
   reference the same underlying MySQL connection.
  </para>
  <para>
   This is similar in concept to connection state related phenomens
   described for the PHP mysqlnd replication and load balancing plugin.
   Please, check the
   <link linkend="book.mysqlnd-ms">PECL/mysqlnd_ms documentation</link> for
   more details on the state of a connection.
  </para>
  <para>
   The proof-of-concept takes no measures to isolate multiplexed
   connections from each other.
  </para>
 </section>

</chapter>

<!-- 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
-->