r1645: *** empty log message ***

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index fcb08ebf8af2ca1e2e2e45629fcfe73eee1a7eef..732204a47c7f6de8fd3eb8c686a1592333db5681 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -877,7 +877,7 @@ can be freed.
          <varlistentry>
            <term><parameter>type</parameter></term>
            <listitem>
-             <para>A unevaluated type of foreign object to allocate.
+             <para>The type of foreign object to allocate. This parameter is evaluated.
              </para>
            </listitem>
          </varlistentry>
@@ -908,7 +908,7 @@ array of <parameter>type</parameter> that is <parameter>size</parameter> members
        <title>Examples</title>
        <programlisting>
 (def-struct ab (a :int) (b :double))
-(allocate-foreign-object ab)
+(allocate-foreign-object 'ab)
 => #&lt;ptr&gt;
        </programlisting>
       </refsect1>
@@ -973,6 +973,79 @@ array of <parameter>type</parameter> that is <parameter>size</parameter> members
     </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>