From 24524dbd7867a27ba0550dbfd2c3fafed5ae0ca5 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Wed, 6 Oct 2010 10:53:49 +0200
Subject: Documentation update to ETS and drivers

State more clearly that ETS functions will throw badarg if calling
process lacks access right. And that driver stop callback should free
memory allocted by start.
---
 erts/doc/src/driver.xml       |  7 +++++--
 erts/doc/src/driver_entry.xml |  6 ++++--
 lib/stdlib/doc/src/ets.xml    | 22 ++++++++++++++--------
 3 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml
index 006a6160de..db455312ec 100644
--- a/erts/doc/src/driver.xml
+++ b/erts/doc/src/driver.xml
@@ -196,11 +196,14 @@ static ErlDrvData start(ErlDrvPort port, char *command)
     <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 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);
+    our_data_t* data = (our_data_t*)drv_data;
+
+    do_disconnect(data, NULL);
+    driver_free(data);
 }
     ]]></code>
     <p>We use the binary format only to return data to the emulator;
diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index e71b48bd92..dd949d4048 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -172,7 +172,7 @@ typedef struct erl_drv_entry {
           added to the driver list.) The driver should return 0, or if
           the driver can't initialize, -1.</p>
       </item>
-      <tag><marker id="start"/>int (*start)(ErlDrvPort port, char* command)</tag>
+      <tag><marker id="start"/>ErlDrvData (*start)(ErlDrvPort port, char* command)</tag>
       <item>
         <p>This is called when the driver is instantiated, when
           <c>open_port/2</c> is called. The driver should return a
@@ -188,7 +188,9 @@ typedef struct erl_drv_entry {
         <p>This is called when the port is closed, with
           <c>port_close/1</c> or <c>Port ! {self(), close}</c>. Note
           that terminating the port owner process also closes the
-          port.</p>
+          port. If <c>drv_data</c> is a pointer to memory allocated in
+	  <c>start</c>, then <c>stop</c> is the place to deallocate that
+	  memory.</p>
       </item>
       <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, int len)</tag>
       <item>
diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml
index dd4a289c61..702e1b928e 100644
--- a/lib/stdlib/doc/src/ets.xml
+++ b/lib/stdlib/doc/src/ets.xml
@@ -56,8 +56,8 @@
       Even if there are no references to a table from any process, it
       will not automatically be destroyed unless the owner process
       terminates. It can be destroyed explicitly by using
-      <c>delete/1</c>.</p>
-    <p>Since R13B01, table ownership can be transferred at process termination
+      <c>delete/1</c>. The default owner is the process that created the
+      table. Table ownership can be transferred at process termination
       by using the <seealso marker="#heir">heir</seealso> option or explicitly
       by calling <seealso marker="#give_away/3">give_away/3</seealso>.</p>
     <p>Some implementation details:</p>
@@ -82,11 +82,15 @@
       <c>float()</c> that extends to the same value, hence the key
       <c>1</c> and the key <c>1.0</c> are regarded as equal in an
       <c>ordered_set</c> table.</p>
-    <p>In general, the functions below will exit with reason
-      <c>badarg</c> if any argument is of the wrong format, or if the
-      table identifier is invalid.</p>
   </description>
-
+  <section>
+    <title>Failure</title>
+    <p>In general, the functions below will exit with reason
+      <c>badarg</c> if any argument is of the wrong format, if the
+      table identifier is invalid or if the operation is denied due to
+      table access rights (<seealso marker="#protected">protected</seealso>
+      or <seealso marker="#private">private</seealso>).</p>
+  </section>
   <section><marker id="concurrency"></marker>
     <title>Concurrency</title>
       <p>This module provides some limited support for concurrent access.
@@ -947,7 +951,7 @@ ets:select(Table,MatchSpec),</code>
       <type>
         <v>Name = atom()</v>
         <v>Options = [Option]</v>
-        <v>&nbsp;Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | {write_concurrency,bool()}</v>
+        <v>&nbsp;Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | {write_concurrency,bool()} | {read_concurrency,bool()}</v>
         <v>&nbsp;&nbsp;Type = set | ordered_set | bag | duplicate_bag</v>
         <v>&nbsp;&nbsp;Access = public | protected | private</v>
         <v>&nbsp;&nbsp;Pos = int()</v>
@@ -963,7 +967,7 @@ ets:select(Table,MatchSpec),</code>
           table is named or not. If one or more options are left out,
           the default values are used. This means that not specifying
           any options (<c>[]</c>) is the same as specifying
-          <c>[set,protected,{keypos,1},{heir,none},{write_concurrency,false}]</c>.</p>
+          <c>[set,protected,{keypos,1},{heir,none},{write_concurrency,false},{read_concurrency,false}]</c>.</p>
         <list type="bulleted">
           <item>
             <p><c>set</c>
@@ -1002,12 +1006,14 @@ ets:select(Table,MatchSpec),</code>
               Any process may read or write to the table.</p>
           </item>
           <item>
+            <marker id="protected"></marker>
             <p><c>protected</c>
               The owner process can read and write to the table. Other
               processes can only read the table. This is the default
               setting for the access rights.</p>
           </item>
           <item>
+            <marker id="private"></marker>
             <p><c>private</c>
               Only the owner process can read or write to the table.</p>
           </item>
-- 
cgit v1.2.3