The R13B03 release.OTP_R13B03

1 files changed, 812 insertions, 0 deletions

diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml
new file mode 100644
index 0000000000..c396ee0b90
--- /dev/null
+++ b/erts/doc/src/driver.xml
@@ -0,0 +1,812 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2001</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>How to implement a driver</title>
+    <prepared>Jakob C</prepared>
+    <docno></docno>
+    <date>2000-11-28</date>
+    <rev>PA1</rev>
+    <file>driver.xml</file>
+  </header>
+
+  <note><p>This document was written a long time ago. A lot of it is still
+           valid, but some things have changed since it was first written.
+	   Updates of this document are planned for the future. The reader
+	   is encouraged to also read the
+	   <seealso marker="erl_driver">erl_driver</seealso>, and the
+	   <seealso marker="erl_driver">driver_entry</seealso> documentation.
+   </p></note>
+
+  <section>
+    <title>Introduction</title>
+    <p>This chapter tells you how to build your own driver for erlang.</p>
+    <p>A driver in Erlang is a library written in C, that is linked to
+      the Erlang emulator and called from erlang. Drivers can be used
+      when C is more suitable than Erlang, to speed things up, or to
+      provide access to OS resources not directly accessible from
+      Erlang.</p>
+    <p>A driver can be dynamically loaded, as a shared library (known as
+      a DLL on windows), or statically loaded, linked with the emulator
+      when it is compiled and linked. Only dynamically loaded drivers
+      are described here, statically linked drivers are beyond the scope
+      of this chapter.</p>
+    <p>When a driver is loaded it is executed in the context of the
+      emulator, shares the same memory and the same thread. This means
+      that all operations in the driver must be non-blocking, and that
+      any crash in the driver will bring the whole emulator down. In
+      short: you have to be extremely careful!</p>
+    <p></p>
+  </section>
+
+  <section>
+    <title>Sample driver</title>
+    <p>This is a simple driver for accessing a postgres
+      database using the libpq C client library. Postgres
+      is used because it's free and open source. For information
+      on postgres, refer to the website www.postgres.org.</p>
+    <p>The driver is synchronous, it uses the synchronous calls of
+      the client library. This is only for simplicity, and is
+      generally not good, since it will
+      halt the emulator while waiting for the database.
+      This will be improved on below with an asynchronous
+      sample driver.</p>
+    <p>The code is quite straight-forward: all
+      communication between Erlang and the driver
+      is done with <c><![CDATA[port_control/3]]></c>, and the
+      driver returns data back using the <c><![CDATA[rbuf]]></c>.</p>
+    <p>An Erlang driver only exports one function: the driver
+      entry function. This is defined with a macro,
+      <c><![CDATA[DRIVER_INIT]]></c>, and returns a pointer to a
+      C <c><![CDATA[struct]]></c> containing the entry points that are
+      called from the emulator. The <c><![CDATA[struct]]></c> defines the
+      entries that the emulator calls to call the driver, with
+      a <c><![CDATA[NULL]]></c> pointer for entries that are not defined
+      and used by the driver.</p>
+    <p>The <c><![CDATA[start]]></c> entry is called when the driver
+      is opened as a port with <c><![CDATA[open_port/2]]></c>. Here
+      we allocate memory for a user data structure.
+      This user data will be passed every time the emulator
+      calls us. First we store the driver handle, because it
+      is needed in subsequent calls. We allocate memory for
+      the connection handle that is used by LibPQ. We also
+      set the port to return allocated driver binaries, by
+      setting the flag <c><![CDATA[PORT_CONTROL_FLAG_BINARY]]></c>, calling
+      <c><![CDATA[set_port_control_flags]]></c>. (This is because
+      we don't know whether our data will fit in the
+      result buffer of <c><![CDATA[control]]></c>, which has a default size
+      set up by the emulator, currently 64 bytes.)</p>
+    <p>There is an entry <c><![CDATA[init]]></c> which is called when
+      the driver is loaded, but we don't use this, since
+      it is executed only once, and we want to have the
+      possibility of several instances of the driver.</p>
+    <p>The <c><![CDATA[stop]]></c> entry is called when the port
+      is closed.</p>
+    <p>The <c><![CDATA[control]]></c> entry is called from the emulator
+      when the Erlang code calls <c><![CDATA[port_control/3]]></c>,
+      to do the actual work. We have defined a simple set of
+      commands: <c><![CDATA[connect]]></c> to login to the database, <c><![CDATA[disconnect]]></c>
+      to log out and <c><![CDATA[select]]></c> to send a SQL-query and get the result.
+      All results are returned through <c><![CDATA[rbuf]]></c>.
+      The library <c><![CDATA[ei]]></c> in <c><![CDATA[erl_interface]]></c> is used
+      to encode data in binary term format. The result is returned
+      to the emulator as binary terms, so <c><![CDATA[binary_to_term]]></c>
+      is called in Erlang to convert the result to term form.</p>
+    <p>The code is available in <c><![CDATA[pg_sync.c]]></c> in the <c><![CDATA[sample]]></c>
+      directory of <c><![CDATA[erts]]></c>.</p>
+    <p>The driver entry contains the functions that
+      will be called by the emulator. In our simple
+      example, we only provide <c><![CDATA[start]]></c>, <c><![CDATA[stop]]></c>
+      and <c><![CDATA[control]]></c>.</p>
+    <code type="none"><![CDATA[
+/* Driver interface declarations */
+static ErlDrvData start(ErlDrvPort port, char *command);
+static void stop(ErlDrvData drv_data);
+static int control(ErlDrvData drv_data, unsigned int command, char *buf, 
+                   int len, char **rbuf, int rlen); 
+
+static ErlDrvEntry pq_driver_entry = {
+    NULL,                        /* init */
+    start, 
+    stop, 
+    NULL,                        /* output */
+    NULL,                        /* ready_input */
+    NULL,                        /* ready_output */ 
+    "pg_sync",                   /* the name of the driver */
+    NULL,                        /* finish */
+    NULL,                        /* handle */
+    control, 
+    NULL,                        /* timeout */
+    NULL,                        /* outputv */
+    NULL,                        /* ready_async */
+    NULL,                        /* flush */
+    NULL,                        /* call */
+    NULL                         /* event */
+};
+    ]]></code>
+    <p>We have a structure to store state needed by the driver,
+      in this case we only need to keep the database connection.</p>
+    <code type="none"><![CDATA[
+typedef struct our_data_s {
+    PGconn* conn;
+} our_data_t;
+    ]]></code>
+    <p>These are control codes we have defined.</p>
+    <code type="none"><![CDATA[
+/* Keep the following definitions in alignment with the
+ * defines in erl_pq_sync.erl
+ */
+
+#define DRV_CONNECT             'C'
+#define DRV_DISCONNECT          'D'
+#define DRV_SELECT              'S'
+    ]]></code>
+    <p>This just returns the driver structure. The macro
+      <c><![CDATA[DRIVER_INIT]]></c> defines the only exported function.
+      All the other functions are static, and will not be exported
+      from the library.</p>
+    <code type="none"><![CDATA[
+/* INITIALIZATION AFTER LOADING */
+
+/* 
+ * This is the init function called after this driver has been loaded.
+ * It must *not* be declared static. Must return the address to 
+ * the driver entry.
+ */
+
+DRIVER_INIT(pq_drv)
+{
+    return &pq_driver_entry;
+}
+    ]]></code>
+    <p>Here we do some initialization, <c><![CDATA[start]]></c> is called from
+      <c><![CDATA[open_port]]></c>. The data will be passed to <c><![CDATA[control]]></c>
+      and <c><![CDATA[stop]]></c>.</p>
+    <code type="none"><![CDATA[
+/* DRIVER INTERFACE */
+static ErlDrvData start(ErlDrvPort port, char *command)
+{ 
+    our_data_t* data;
+
+    data = (our_data_t*)driver_alloc(sizeof(our_data_t));
+    data->conn = NULL;
+    set_port_control_flags(port, PORT_CONTROL_FLAG_BINARY);
+    return (ErlDrvData)data;
+}
+    ]]></code>
+    <p>We call disconnect to log out from the database.
+      (This should have been done from Erlang, but just in case.)</p>
+    <code type="none"><![CDATA[
+ static int do_disconnect(our_data_t* data, ei_x_buff* x);
+
+static void stop(ErlDrvData drv_data)
+{
+    do_disconnect((our_data_t*)drv_data, NULL);
+}
+    ]]></code>
+    <p>We use the binary format only to return data to the emulator;
+      input data is a string paramater for <c><![CDATA[connect]]></c> and
+      <c><![CDATA[select]]></c>. The returned data consists of Erlang terms.</p>
+    <p>The functions <c><![CDATA[get_s]]></c> and <c><![CDATA[ei_x_to_new_binary]]></c> are
+      utilities that is used to make the code shorter. <c><![CDATA[get_s]]></c>
+      duplicates the string and zero-terminates it, since the
+      postgres client library wants that. <c><![CDATA[ei_x_to_new_binary]]></c>
+      takes an <c><![CDATA[ei_x_buff]]></c> buffer and allocates a binary and
+      copies the data there. This binary is returned in <c><![CDATA[*rbuf]]></c>.
+      (Note that this binary is freed by the emulator, not by us.)</p>
+    <code type="none"><![CDATA[
+static char* get_s(const char* buf, int len);
+static int do_connect(const char *s, our_data_t* data, ei_x_buff* x);
+static int do_select(const char* s, our_data_t* data, ei_x_buff* x);
+
+/* Since we are operating in binary mode, the return value from control
+ * is irrelevant, as long as it is not negative.
+ */
+static int control(ErlDrvData drv_data, unsigned int command, char *buf, 
+                   int len, char **rbuf, int rlen)
+{
+    int r;
+    ei_x_buff x;
+    our_data_t* data = (our_data_t*)drv_data;
+    char* s = get_s(buf, len);
+    ei_x_new_with_version(&x);
+    switch (command) {
+        case DRV_CONNECT:    r = do_connect(s, data, &x);  break;
+        case DRV_DISCONNECT: r = do_disconnect(data, &x);  break;
+        case DRV_SELECT:     r = do_select(s, data, &x);   break;
+        default:             r = -1;        break;
+    }
+    *rbuf = (char*)ei_x_to_new_binary(&x);
+    ei_x_free(&x);
+    driver_free(s);
+    return r;
+}
+    ]]></code>
+    <p>In <c><![CDATA[do_connect]]></c> is where we log in to the database. If the connection
+      was successful we store the connection handle in our driver
+      data, and return ok. Otherwise, we return the error message
+      from postgres, and store <c><![CDATA[NULL]]></c> in the driver data.</p>
+    <code type="none"><![CDATA[
+static int do_connect(const char *s, our_data_t* data, ei_x_buff* x)
+{
+    PGconn* conn = PQconnectdb(s);
+    if (PQstatus(conn) != CONNECTION_OK) {
+        encode_error(x, conn);
+        PQfinish(conn);
+        conn = NULL;
+    } else {
+        encode_ok(x);
+    }
+    data->conn = conn;
+    return 0;
+}
+    ]]></code>
+    <p>If we are connected (if the connection handle is not <c><![CDATA[NULL]]></c>),
+      we log out from the database. We need to check if a we should
+      encode an ok, since we might get here from the <c><![CDATA[stop]]></c>
+      function, which doesn't return data to the emulator.</p>
+    <code type="none"><![CDATA[
+static int do_disconnect(our_data_t* data, ei_x_buff* x)
+{
+    if (data->conn == NULL)
+        return 0;
+    PQfinish(data->conn);
+    data->conn = NULL;
+    if (x != NULL)
+        encode_ok(x);
+    return 0;
+}
+    ]]></code>
+    <p>We execute a query and encodes the result. Encoding is done
+      in another C module, <c><![CDATA[pg_encode.c]]></c> which is also provided
+      as sample code.</p>
+    <code type="none"><![CDATA[
+static int do_select(const char* s, our_data_t* data, ei_x_buff* x)
+{
+   PGresult* res = PQexec(data->conn, s);
+    encode_result(x, res, data->conn);
+    PQclear(res);
+    return 0;
+}
+    ]]></code>
+    <p>Here we simply checks the result from postgres, and
+      if it's data we encode it as lists of lists with
+      column data. Everything from postgres is C strings,
+      so we just use <c><![CDATA[ei_x_encode_string]]></c> to send
+      the result as strings to Erlang. (The head of the list
+      contains the column names.)</p>
+    <code type="none"><![CDATA[
+void encode_result(ei_x_buff* x, PGresult* res, PGconn* conn)
+{
+    int row, n_rows, col, n_cols;
+    switch (PQresultStatus(res)) {
+    case PGRES_TUPLES_OK: 
+        n_rows = PQntuples(res); 
+        n_cols = PQnfields(res); 
+        ei_x_encode_tuple_header(x, 2);
+        encode_ok(x);
+        ei_x_encode_list_header(x, n_rows+1);
+        ei_x_encode_list_header(x, n_cols);
+        for (col = 0; col < n_cols; ++col) {
+            ei_x_encode_string(x, PQfname(res, col));
+        }
+        ei_x_encode_empty_list(x); 
+        for (row = 0; row < n_rows; ++row) {
+            ei_x_encode_list_header(x, n_cols);
+            for (col = 0; col < n_cols; ++col) {
+                ei_x_encode_string(x, PQgetvalue(res, row, col));
+            }
+            ei_x_encode_empty_list(x);
+        }
+        ei_x_encode_empty_list(x); 
+        break; 
+    case PGRES_COMMAND_OK:
+        ei_x_encode_tuple_header(x, 2);
+        encode_ok(x);
+        ei_x_encode_string(x, PQcmdTuples(res));
+        break;
+    default:
+        encode_error(x, conn);
+        break;
+    }
+}
+    ]]></code>
+  </section>
+
+  <section>
+    <title>Compiling and linking the sample driver</title>
+    <p>The driver should be compiled and linked to a shared
+      library (DLL on windows). With gcc this is done
+      with the link flags <c><![CDATA[-shared]]></c> and <c><![CDATA[-fpic]]></c>.
+      Since we use the <c><![CDATA[ei]]></c> library we should include
+      it too. There are several versions of <c><![CDATA[ei]]></c>, compiled
+      for debug or non-debug and multi-threaded or single-threaded.
+      In the makefile for the samples the <c><![CDATA[obj]]></c> directory
+      is used for the <c><![CDATA[ei]]></c> library, meaning that we use
+      the non-debug, single-threaded version.</p>
+  </section>
+
+  <section>
+    <title>Calling a driver as a port in Erlang</title>
+    <p>Before a driver can be called from Erlang, it must be
+      loaded and opened. Loading is done using the <c><![CDATA[erl_ddll]]></c>
+      module (the <c><![CDATA[erl_ddll]]></c> driver that loads dynamic
+      driver, is actually a driver itself). If loading is ok
+      the port can be opened with <c><![CDATA[open_port/2]]></c>. The port
+      name must match the name of the shared library and
+      the name in the driver entry structure.</p>
+    <p>When the port has been opened, the driver can be called. In
+      the <c><![CDATA[pg_sync]]></c> example, we don't have any data from
+      the port, only the return value from the
+      <c><![CDATA[port_control]]></c>.</p>
+    <p>The following code is the Erlang part of the synchronous
+      postgres driver, <c><![CDATA[pg_sync.erl]]></c>.</p>
+    <code type="none"><![CDATA[
+-module(pg_sync).
+
+-define(DRV_CONNECT, 1).
+-define(DRV_DISCONNECT, 2).
+-define(DRV_SELECT, 3).
+
+-export([connect/1, disconnect/1, select/2]).
+
+connect(ConnectStr) ->
+    case erl_ddll:load_driver(".", "pg_sync") of
+        ok -> ok;
+        {error, already_loaded} -> ok;
+        E -> exit({error, E})
+    end,
+    Port = open_port({spawn, ?MODULE}, []),
+    case binary_to_term(port_control(Port, ?DRV_CONNECT, ConnectStr)) of
+        ok -> {ok, Port};
+        Error -> Error
+    end.
+
+disconnect(Port) ->
+    R = binary_to_term(port_control(Port, ?DRV_DISCONNECT, "")),
+    port_close(Port),
+    R.
+
+select(Port, Query) ->
+    binary_to_term(port_control(Port, ?DRV_SELECT, Query)).
+    ]]></code>
+    <p>The api is simple: <c><![CDATA[connect/1]]></c> loads the driver, opens it
+      and logs on to the database, returning the Erlang port
+      if successful, <c><![CDATA[select/2]]></c> sends a query to the driver,
+      and returns the result, <c><![CDATA[disconnect/1]]></c> closes the
+      database connection and the driver. (It does not unload it,
+      however.) The connection string should be a connection
+      string for postgres.</p>
+    <p>The driver is loaded with <c><![CDATA[erl_ddll:load_driver/2]]></c>,
+      and if this is successful, or if it's already loaded,
+      it is opened. This will call the <c><![CDATA[start]]></c> function
+      in the driver.</p>
+    <p>We use the <c><![CDATA[port_control/3]]></c> function for all
+      calls into the driver, the result from the driver is
+      returned immediately, and converted to terms by calling
+      <c><![CDATA[binary_to_term/1]]></c>. (We trust that the terms returned
+      from the driver are well-formed, otherwise the
+      <c><![CDATA[binary_to_term]]></c> calls could be contained in a
+      <c><![CDATA[catch]]></c>.)</p>
+  </section>
+
+  <section>
+    <title>Sample asynchronous driver</title>
+    <p>Sometimes database queries can take long time to
+      complete, in our <c><![CDATA[pg_sync]]></c> driver, the emulator
+      halts while the driver is doing it's job. This is
+      often not acceptable, since no other Erlang processes
+      gets a chance to do anything. To improve on our
+      postgres driver, we reimplement it using the asynchronous
+      calls in LibPQ.</p>
+    <p>The asynchronous version of the driver is in the
+      sample files <c><![CDATA[pg_async.c]]></c> and <c><![CDATA[pg_asyng.erl]]></c>.</p>
+    <code type="none"><![CDATA[
+/* Driver interface declarations */
+static ErlDrvData start(ErlDrvPort port, char *command);
+static void stop(ErlDrvData drv_data);
+static int control(ErlDrvData drv_data, unsigned int command, char *buf, 
+                   int len, char **rbuf, int rlen); 
+static void ready_io(ErlDrvData drv_data, ErlDrvEvent event);
+
+static ErlDrvEntry pq_driver_entry = {
+    NULL,                     /* init */
+    start, 
+    stop, 
+    NULL,                     /* output */
+    ready_io,                 /* ready_input */
+    ready_io,                 /* ready_output */ 
+    "pg_async",               /* the name of the driver */
+    NULL,                     /* finish */
+    NULL,                     /* handle */
+    control, 
+    NULL,                     /* timeout */
+    NULL,                     /* outputv */
+    NULL,                     /* ready_async */
+    NULL,                     /* flush */
+    NULL,                     /* call */
+    NULL                      /* event */
+};
+
+typedef struct our_data_t {
+    PGconn* conn;
+    ErlDrvPort port;
+    int socket;
+    int connecting;
+} our_data_t;
+    ]]></code>
+    <p>Here some things have changed from <c><![CDATA[pg_sync.c]]></c>: we use the
+      entry <c><![CDATA[ready_io]]></c> for <c><![CDATA[ready_input]]></c> and
+      <c><![CDATA[ready_output]]></c> which will be called from the emulator only
+      when there is input to be read from the socket. (Actually, the
+      socket is used in a <c><![CDATA[select]]></c> function inside
+      the emulator, and when the socket is signalled,
+      indicating there is data to read, the <c><![CDATA[ready_input]]></c> entry
+      is called. More on this below.)</p>
+    <p>Our driver data is also extended, we keep track of the
+      socket used for communication with postgres, and also
+      the port, which is needed when we send data to the port with
+      <c><![CDATA[driver_output]]></c>. We have a flag <c><![CDATA[connecting]]></c> to tell
+      whether the driver is waiting for a connection or waiting
+      for the result of a query. (This is needed since the entry
+      <c><![CDATA[ready_io]]></c> will be called both when connecting and
+      when there is query result.)</p>
+    <code type="none"><![CDATA[
+static int do_connect(const char *s, our_data_t* data)
+{
+    PGconn* conn = PQconnectStart(s);
+    if (PQstatus(conn) == CONNECTION_BAD) {
+        ei_x_buff x;
+        ei_x_new_with_version(&x);
+        encode_error(&x, conn);
+        PQfinish(conn);
+        conn = NULL;
+        driver_output(data->port, x.buff, x.index);
+        ei_x_free(&x);
+    }
+    PQconnectPoll(conn);
+    int socket = PQsocket(conn);
+    data->socket = socket;
+    driver_select(data->port, (ErlDrvEvent)socket, DO_READ, 1);
+    driver_select(data->port, (ErlDrvEvent)socket, DO_WRITE, 1);
+    data->conn = conn;
+    data->connecting = 1;
+    return 0;
+}
+    ]]></code>
+    <p>The <c><![CDATA[connect]]></c> function looks a bit different too. We connect
+      using the asynchronous <c><![CDATA[PQconnectStart]]></c> function. After the
+      connection is started, we retrieve the socket for the connection
+      with <c><![CDATA[PQsocket]]></c>. This socket is used with the
+      <c><![CDATA[driver_select]]></c> function to wait for connection. When
+      the socket is ready for input or for output, the <c><![CDATA[ready_io]]></c>
+      function will be called.</p>
+    <p>Note that we only return data (with <c><![CDATA[driver_output]]></c>) if there
+      is an error here, otherwise we wait for the connection to be completed,
+      in which case our <c><![CDATA[ready_io]]></c> function will be called.</p>
+    <code type="none"><![CDATA[
+static int do_select(const char* s, our_data_t* data)
+{
+    data->connecting = 0;
+    PGconn* conn = data->conn;
+    /* if there's an error return it now */
+    if (PQsendQuery(conn, s) == 0) {
+\011ei_x_buff x;
+\011ei_x_new_with_version(&x);
+\011encode_error(&x, conn);
+\011driver_output(data->port, x.buff, x.index);
+\011ei_x_free(&x);
+    }
+    /* else wait for ready_output to get results */
+    return 0;
+}
+    ]]></code>
+    <p>The <c><![CDATA[do_select]]></c> function initiates a select, and returns
+      if there is no immediate error. The actual result will be returned
+      when <c><![CDATA[ready_io]]></c> is called.</p>
+    <code type="none"><![CDATA[
+static void ready_io(ErlDrvData drv_data, ErlDrvEvent event)
+{
+    PGresult* res = NULL;
+    our_data_t* data = (our_data_t*)drv_data;
+    PGconn* conn = data->conn;
+    ei_x_buff x;
+    ei_x_new_with_version(&x);
+    if (data->connecting) {
+\011ConnStatusType status;
+\011PQconnectPoll(conn);
+\011status = PQstatus(conn);
+\011if (status == CONNECTION_OK)
+\011    encode_ok(&x);
+\011else if (status == CONNECTION_BAD)
+\011    encode_error(&x, conn);
+    } else {
+\011PQconsumeInput(conn);
+\011if (PQisBusy(conn))
+\011    return;
+\011res = PQgetResult(conn);
+\011encode_result(&x, res, conn);
+\011PQclear(res);
+\011for (;;) {
+\011    res = PQgetResult(conn);
+\011    if (res == NULL)
+\011\011break;
+\011    PQclear(res);
+\011}
+    }
+    if (x.index > 1) {
+\011driver_output(data->port, x.buff, x.index);
+\011if (data->connecting) 
+\011    driver_select(data->port, (ErlDrvEvent)data->socket, DO_WRITE, 0);
+    }
+    ei_x_free(&x);
+}
+    ]]></code>
+    <p>The <c><![CDATA[ready_io]]></c> function will be called when the socket
+      we got from postgres is ready for input or output. Here
+      we first check if we are connecting to the database. In that
+      case we check connection status and return ok if the 
+      connection is successful, or error if it's not. If the
+      connection is not yet established, we simply return; <c><![CDATA[ready_io]]></c>
+      will be called again.</p>
+    <p>If we have result from a connect, indicated that we have data in
+      the <c><![CDATA[x]]></c> buffer, we no longer need to select on
+      output (<c><![CDATA[ready_output]]></c>), so we remove this by calling
+      <c><![CDATA[driver_select]]></c>.</p>
+    <p>If we're not connecting, we're waiting for results from a
+      <c><![CDATA[PQsendQuery]]></c>, so we get the result and return it. The
+      encoding is done with the same functions as in the earlier
+      example.</p>
+    <p>We should add error handling here, for instance checking
+      that the socket is still open, but this is just a simple
+      example.</p>
+    <p>The Erlang part of the asynchronous driver consists of the
+      sample file <c><![CDATA[pg_async.erl]]></c>.</p>
+    <code type="none"><![CDATA[
+-module(pg_async).
+
+-define(DRV_CONNECT, $C).
+-define(DRV_DISCONNECT, $D).
+-define(DRV_SELECT, $S).
+
+-export([connect/1, disconnect/1, select/2]).
+
+connect(ConnectStr) ->
+    case erl_ddll:load_driver(".", "pg_async") of
+\011ok -> ok;
+\011{error, already_loaded} -> ok;
+\011_ -> exit({error, could_not_load_driver})
+    end,
+    Port = open_port({spawn, ?MODULE}, [binary]),
+    port_control(Port, ?DRV_CONNECT, ConnectStr),
+    case return_port_data(Port) of
+\011ok -> 
+\011    {ok, Port};
+\011Error ->
+\011    Error
+    end.    
+
+disconnect(Port) ->
+    port_control(Port, ?DRV_DISCONNECT, ""),
+    R = return_port_data(Port),
+    port_close(Port),
+    R.
+
+select(Port, Query) ->
+    port_control(Port, ?DRV_SELECT, Query),
+    return_port_data(Port).
+
+return_port_data(Port) ->
+    receive
+\011{Port, {data, Data}} ->
+\011    binary_to_term(Data)
+    end.
+    ]]></code>
+    <p>The Erlang code is slightly different, this is because we
+      don't return the result synchronously from <c><![CDATA[port_control]]></c>,
+      instead we get it from <c><![CDATA[driver_output]]></c> as data in the
+      message queue. The function <c><![CDATA[return_port_data]]></c> above
+      receives data from the port. Since the data is in
+      binary format, we use <c><![CDATA[binary_to_term/1]]></c> to convert
+      it to Erlang term. Note that the driver is opened in
+      binary mode, <c><![CDATA[open_port/2]]></c> is called with the option
+      <c><![CDATA[[binary]]]></c>. This means that data sent from the driver
+      to the emulator is sent as binaries. Without the <c><![CDATA[binary]]></c>
+      option, they would have been lists of integers.</p>
+  </section>
+
+  <section>
+    <title>An asynchronous driver using driver_async</title>
+    <p>As a final example we demonstrate the use of <c><![CDATA[driver_async]]></c>.
+      We also use the driver term interface. The driver is written
+      in C++. This enables us to use an algorithm from STL. We will
+      use the <c><![CDATA[next_permutation]]></c> algorithm to get the next permutation
+      of a list of integers. For large lists (more than 100000
+      elements), this will take some time, so we will perform this
+      as an asynchronous task.</p>
+    <p>The asynchronous api for drivers are quite complicated. First
+      of all, the work must be prepared. In our example we do this
+      in <c><![CDATA[output]]></c>. We could have used <c><![CDATA[control]]></c> just as well,
+      but we want some variation in our examples. In our driver, we allocate
+      a structure that contains all needed for the asynchronous task
+      to do the work. This is done in the main emulator thread.
+      Then the asynchronous function is called from a driver thread,
+      separate from the main emulator thread. Note that the driver-
+      functions are not reentrant, so they shouldn't be used.
+      Finally, after the function is completed, the driver callback
+      <c><![CDATA[ready_async]]></c> is called from the main emulator thread,
+      this is where we return the result to Erlang. (We can't
+      return the result from within the asynchronous function, since
+      we can't call the driver-functions.)</p>
+    <p>The code below is from the sample file <c><![CDATA[next_perm.cc]]></c>.</p>
+    <p>The driver entry looks like before, but also contains the
+      call-back <c><![CDATA[ready_async]]></c>.</p>
+    <code type="none"><![CDATA[
+static ErlDrvEntry next_perm_driver_entry = {
+    NULL,\011\011\011/* init */
+    start,
+    NULL, \011\011\011/* stop */
+    output,\011\011\011
+    NULL,\011\011\011/* ready_input */
+    NULL,\011\011\011/* ready_output */ 
+    "next_perm",                /* the name of the driver */
+    NULL,\011\011\011/* finish */
+    NULL,\011\011\011/* handle */
+    NULL,\011\011\011/* control */
+    NULL,\011\011\011/* timeout */
+    NULL,\011\011\011/* outputv */
+    ready_async,
+    NULL,\011\011\011/* flush */
+    NULL,\011\011\011/* call */
+    NULL\011\011\011/* event */
+};
+    ]]></code>
+    <p>The <c><![CDATA[output]]></c> function allocates the work-area of the
+      asynchronous function. Since we use C++, we use a struct,
+      and stuff the data in it. We have to copy the original data,
+      it is not valid after we have returned from the <c><![CDATA[output]]></c>
+      function, and the <c><![CDATA[do_perm]]></c> function will be called later,
+      and from another thread. We return no data here, instead it will
+      be sent later from the <c><![CDATA[ready_async]]></c> call-back.</p>
+    <p>The <c><![CDATA[async_data]]></c> will be passed to the <c><![CDATA[do_perm]]></c> function.
+      We do not use a <c><![CDATA[async_free]]></c> function (the last argument to
+      <c><![CDATA[driver_async]]></c>, it's only used if the task is cancelled
+      programmatically.</p>
+    <code type="none"><![CDATA[
+struct our_async_data {
+    bool prev;
+    vector<int> data;
+    our_async_data(ErlDrvPort p, int command, const char* buf, int len);
+};
+
+our_async_data::our_async_data(ErlDrvPort p, int command,
+\011\011\011       const char* buf, int len)
+    : prev(command == 2),
+      data((int*)buf, (int*)buf + len / sizeof(int))
+{
+}
+
+static void do_perm(void* async_data);
+
+static void output(ErlDrvData drv_data, char *buf, int len)
+{
+    if (*buf < 1 || *buf > 2) return;
+    ErlDrvPort port = reinterpret_cast<ErlDrvPort>(drv_data);
+    void* async_data = new our_async_data(port, *buf, buf+1, len);
+    driver_async(port, NULL, do_perm, async_data, do_free);
+}
+    ]]></code>
+    <p>In the <c><![CDATA[do_perm]]></c> we simply do the work, operating
+      on the structure that was allocated in <c><![CDATA[output]]></c>.</p>
+    <code type="none"><![CDATA[
+static void do_perm(void* async_data)
+{
+    our_async_data* d = reinterpret_cast<our_async_data*>(async_data);
+    if (d->prev)
+\011prev_permutation(d->data.begin(), d->data.end());
+    else
+\011next_permutation(d->data.begin(), d->data.end());
+}
+    ]]></code>
+    <p>In the <c><![CDATA[ready_async]]></c> function, the output is sent back to the
+      emulator. We use the driver term format instead of <c><![CDATA[ei]]></c>.
+      This is the only way to send Erlang terms directly to a driver,
+      without having the Erlang code to call <c><![CDATA[binary_to_term/1]]></c>. In
+      our simple example this works well, and we don't need to use
+      <c><![CDATA[ei]]></c> to handle the binary term format.</p>
+    <p>When the data is returned we deallocate our data.</p>
+    <code type="none"><![CDATA[
+static void ready_async(ErlDrvData drv_data, ErlDrvThreadData async_data)
+{
+    ErlDrvPort port = reinterpret_cast<ErlDrvPort>(drv_data);
+    our_async_data* d = reinterpret_cast<our_async_data*>(async_data);
+    int n = d->data.size(), result_n = n*2 + 3;
+    ErlDrvTermData* result = new ErlDrvTermData[result_n], * rp = result;
+    for (vector<int>::iterator i = d->data.begin();
+\011 i != d->data.end(); ++i) {
+\011*rp++ = ERL_DRV_INT;
+\011*rp++ = *i;
+    }
+    *rp++ = ERL_DRV_NIL;
+    *rp++ = ERL_DRV_LIST;
+    *rp++ = n+1;
+    driver_output_term(port, result, result_n);    
+    delete[] result;
+    delete d;
+}
+    ]]></code>
+    <p>This driver is called like the others from Erlang, however, since
+      we use <c><![CDATA[driver_output_term]]></c>, there is no need to call
+      binary_to_term. The Erlang code is in the sample file
+      <c><![CDATA[next_perm.erl]]></c>.</p>
+    <p>The input is changed into a list of integers and sent to
+      the driver.</p>
+    <code type="none"><![CDATA[
+-module(next_perm).
+
+-export([next_perm/1, prev_perm/1, load/0, all_perm/1]).
+
+load() ->
+    case whereis(next_perm) of
+\011undefined ->
+\011    case erl_ddll:load_driver(".", "next_perm") of
+\011\011ok -> ok;
+\011\011{error, already_loaded} -> ok;
+\011\011E -> exit(E)
+\011    end,
+\011    Port = open_port({spawn, "next_perm"}, []),
+\011    register(next_perm, Port);
+\011_ ->
+\011    ok
+    end.
+
+list_to_integer_binaries(L) ->
+    [<<I:32/integer-native>> || I <- L].
+
+next_perm(L) ->
+    next_perm(L, 1).
+
+prev_perm(L) ->
+    next_perm(L, 2).
+
+next_perm(L, Nxt) ->
+    load(),
+    B = list_to_integer_binaries(L),
+    port_control(next_perm, Nxt, B),
+    receive
+\011Result ->
+\011    Result
+    end.
+
+all_perm(L) ->
+    New = prev_perm(L),
+    all_perm(New, L, [New]).
+
+all_perm(L, L, Acc) ->
+    Acc;
+all_perm(L, Orig, Acc) ->
+    New = prev_perm(L),
+    all_perm(New, Orig, [New | Acc]).
+    ]]></code>
+  </section>
+</chapter>
+