X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=732204a47c7f6de8fd3eb8c686a1592333db5681;hb=79cd30e5bb24c5a8d2eea188e15109e544f8638b;hp=82ee66a5df717e7d9ed15cbbfa5e3d8d607c39f1;hpb=d3f9b63d9227cc2fb7b978e4b40b9592c04852ab;p=uffi.git

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 82ee66a..732204a 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -315,7 +315,7 @@ abstracts the difference in implementations where some return a
       <refsect1>
 	<title>Examples</title>
 	<programlisting>
-(def-array ca :char)
+(def-array-pointer ca :unsigned-char)
 (let ((fs (convert-to-foreign-string "ab")))
    (values (null-char-p (deref-array fs 'ca 0))
            (null-char-p (deref-array fs 'ca 2))))
@@ -640,17 +640,17 @@ structure. It's type is <constant>:pointer-self</constant>.
     </refentry>
 
 
-    <refentry id="def-array">
+    <refentry id="def-array-pointer">
       <refnamediv>
-	<refname>def-array</refname>
-	<refpurpose>Defines a foreign array type.
+	<refname>def-array-pointer</refname>
+	<refpurpose>Defines a pointer to a array of type.
 	</refpurpose>
 	<refclass>Macro</refclass>
       </refnamediv>
       <refsynopsisdiv>
 	<title>Syntax</title>
 	<synopsis>
-	  <function>def-array</function> <replaceable>name type</replaceable>
+	  <function>def-array-pointer</function> <replaceable>name type</replaceable>
 	</synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -675,13 +675,13 @@ structure. It's type is <constant>:pointer-self</constant>.
       <refsect1>
 	<title>Description</title>
 	<para>
-	  Defines a foreign array type.
+	  Defines a type tat is a pointer to an array of type.
 	</para>
       </refsect1>
       <refsect1>
 	<title>Examples</title>
 	<programlisting>
-(def-array byte-array :unsigned-char)
+(def-array-pointer byte-array-pointer :unsigned-char)
 	</programlisting>
       </refsect1>
       <refsect1>
@@ -868,7 +868,7 @@ can be freed.
       <refsynopsisdiv>
 	<title>Syntax</title>
 	<synopsis>
-	  <function>allocate-foreign-object</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
+	  <function>allocate-foreign-object</function> <replaceable>type &amp;optional size</replaceable> => <returnvalue>ptr</returnvalue>
 	</synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -877,7 +877,15 @@ can be freed.
 	  <varlistentry>
 	    <term><parameter>type</parameter></term>
 	    <listitem>
-	      <para>A type of foreign object to allocate.
+	      <para>The type of foreign object to allocate. This parameter is evaluated.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>size</parameter></term>
+	    <listitem>
+	      <para>An optional size parameter. If specified, allocates and returns an
+array of <parameter>type</parameter> that is <parameter>size</parameter> members long.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -900,7 +908,7 @@ can be freed.
 	<title>Examples</title>
 	<programlisting>
 (def-struct ab (a :int) (b :double))
-(allocate-foreign-object ab)
+(allocate-foreign-object 'ab)
 => #&lt;ptr&gt;
 	</programlisting>
       </refsect1>
@@ -965,6 +973,79 @@ can be freed.
     </refentry>
 
 
+    <refentry id="with-foreign-object">
+      <refnamediv>
+	<refname>with-foreign-object</refname>
+	<refpurpose>Wraps the allocation of a foreign object around a body of code.
+	</refpurpose>
+	<refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+	<title>Syntax</title>
+	<synopsis>
+	  <function>with-foreign-object</function> <replaceable>(var type) &amp;body body</replaceable> => <returnvalue>form-return</returnvalue>
+	</synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+	<title>Arguments and Values</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem>
+	      <para>The variable name to bind.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem>
+	      <para>The type of foreign object to allocate. This parameter is evaluated.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><returnvalue>form-return</returnvalue></term>
+	    <listitem>
+	      <para>The result of evaluating the <parameter>body</parameter>.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Description</title>
+	<para>
+This function wraps the allocation, binding, and destruction of a foreign object.
+On &cmucl; and
+&lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
+much better with static allocation.
+	</para>
+      </refsect1>
+      <refsect1>
+	<title>Examples</title>
+	<programlisting>
+(defun gethostname2 ()
+  "Returns the hostname"
+  (uffi:with-foreign-object (name '(:array :unsigned-char 256))
+    (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
+	(uffi:convert-from-foreign-string name)
+	(error "gethostname() failed."))))
+	</programlisting>
+      </refsect1>
+      <refsect1>
+	<title>Side Effects</title>
+	<para>None.</para>
+      </refsect1>
+      <refsect1>
+	<title>Affected by</title>
+	<para>None.</para>
+      </refsect1>
+      <refsect1>
+	<title>Exceptional Situations</title>
+	<para>None.</para>
+      </refsect1>
+    </refentry>
+
     <refentry id="pointer-address">
       <refnamediv>
 	<refname>pointer-address</refname>
@@ -1093,7 +1174,7 @@ can be freed.
     <refentry id="ensure-char-character">
       <refnamediv>
 	<refname>ensure-char-character</refname>
-	<refpurpose>Ensures that a dereferenced :char pointer is
+	<refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
 a character.
 	</refpurpose>
 	<refclass>Macro</refclass>
@@ -1161,7 +1242,7 @@ integer.</para>
     <refentry id="ensure-char-integer">
       <refnamediv>
 	<refname>ensure-char-integer</refname>
-	<refpurpose>Ensures that a dereferenced :char pointer is
+	<refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
 an integer.
 	</refpurpose>
 	<refclass>Macro</refclass>