patches/closure-api-example-doc

   1 Index: libffi/doc/libffi.info
   2 ===================================================================
   3 --- libffi.orig/doc/libffi.info
   4 +++ libffi/doc/libffi.info
   5 @@ -4,7 +4,7 @@ This is doc/libffi.info, produced by mak
   6  This manual is for Libffi, a portable foreign-function interface
   7  library.
   8
   9 -   Copyright (C) 2008 Red Hat, Inc.
  10 +   Copyright (C) 2008, 2010 Red Hat, Inc.
  11
  12       Permission is granted to copy, distribute and/or modify this
  13       document under the terms of the GNU General Public License as
  14 @@ -27,7 +27,7 @@ libffi
  15  This manual is for Libffi, a portable foreign-function interface
  16  library.
  17
  18 -   Copyright (C) 2008 Red Hat, Inc.
  19 +   Copyright (C) 2008, 2010 Red Hat, Inc.
  20
  21       Permission is granted to copy, distribute and/or modify this
  22       document under the terms of the GNU General Public License as
  23 @@ -89,6 +89,7 @@ File: libffi.info,  Node: Using libffi,
  24  * Types::                       libffi type descriptions.
  25  * Multiple ABIs::               Different passing styles on one platform.
  26  * The Closure API::             Writing a generic function.
  27 +* Closure Example::             A closure example.
  28
  29  \1f
  30  File: libffi.info,  Node: The Basics,  Next: Simple Example,  Up: Using libffi
  31 @@ -368,7 +369,7 @@ instance, the x86 platform has both `std
  32  necessarily platform-specific.
  33
  34  \1f
  35 -File: libffi.info,  Node: The Closure API,  Prev: Multiple ABIs,  Up: Using libffi
  36 +File: libffi.info,  Node: The Closure API,  Next: Closure Example,  Prev: Multiple ABIs,  Up: Using libffi
  37
  38  2.5 The Closure API
  39  ===================
  40 @@ -444,6 +445,62 @@ is deprecated, as it cannot handle the n
  41  executable addresses.
  42
  43  \1f
  44 +File: libffi.info,  Node: Closure Example,  Prev: The Closure API,  Up: Using libffi
  45 +
  46 +2.6 Closure Example
  47 +===================
  48 +
  49 +A trivial example that creates a new `puts' by binding `fputs' with
  50 +`stdin'.
  51 +
  52 +     #include <stdio.h>
  53 +     #include <ffi.h>
  54 +
  55 +     /* Acts like puts with the file given at time of enclosure. */
  56 +     void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[],
  57 +                       FILE *stream)
  58 +     {
  59 +       *ret = fputs(*(char **)args[0], stream);
  60 +     }
  61 +
  62 +     int main()
  63 +     {
  64 +       ffi_cif cif;
  65 +       ffi_type *args[1];
  66 +       ffi_closure *closure;
  67 +
  68 +       int (*bound_puts)(char *);
  69 +       int rc;
  70 +
  71 +       /* Allocate closure and bound_puts */
  72 +       closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
  73 +
  74 +       if (closure)
  75 +         {
  76 +           /* Initialize the argument info vectors */
  77 +           args[0] = &ffi_type_pointer;
  78 +
  79 +           /* Initialize the cif */
  80 +           if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
  81 +                            &ffi_type_uint, args) == FFI_OK)
  82 +             {
  83 +               /* Initialize the closure, setting stream to stdout */
  84 +               if (ffi_prep_closure_loc(closure, &cif, puts_binding,
  85 +                                        stdout, bound_puts) == FFI_OK)
  86 +                 {
  87 +                   rc = bound_puts("Hello World!");
  88 +                   /* rc now holds the result of the call to fputs */
  89 +                 }
  90 +             }
  91 +         }
  92 +
  93 +       /* Deallocate both closure, and bound_puts */
  94 +       ffi_closure_free(closure);
  95 +
  96 +       return 0;
  97 +     }
  98 +
  99 +\1f
 100  File: libffi.info,  Node: Missing Features,  Next: Index,  Prev: Using libffi,  Up: Top
 101
 102  3 Missing Features
 103 Index: libffi/doc/libffi.texi
 104 ===================================================================
 105 --- libffi.orig/doc/libffi.texi
 106 +++ libffi/doc/libffi.texi
 107 @@ -19,7 +19,7 @@
 108  This manual is for Libffi, a portable foreign-function interface
 109  library.
 110
 111 -Copyright @copyright{} 2008 Red Hat, Inc.
 112 +Copyright @copyright{} 2008, 2010 Red Hat, Inc.
 113
 114  @quotation
 115  Permission is granted to copy, distribute and/or modify this document
 116 @@ -106,6 +106,7 @@ values passed between the two languages.
 117  * Types::                       libffi type descriptions.
 118  * Multiple ABIs::               Different passing styles on one platform.
 119  * The Closure API::             Writing a generic function.
 120 +* Closure Example::             A closure example.
 121  @end menu
 122
 123
 124 @@ -500,12 +501,66 @@ After calling @code{ffi_prep_closure_loc
 125  to the appropriate pointer-to-function type.
 126  @end defun
 127
 128 -@c FIXME: example
 129 -
 130  You may see old code referring to @code{ffi_prep_closure}.  This
 131  function is deprecated, as it cannot handle the need for separate
 132  writable and executable addresses.
 133
 134 +@node Closure Example
 135 +@section Closure Example
 136 +
 137 +A trivial example that creates a new @code{puts} by binding
 138 +@code{fputs} with @code{stdin}.
 139 +
 140 +@example
 141 +#include <stdio.h>
 142 +#include <ffi.h>
 143 +
 144 +/* Acts like puts with the file given at time of enclosure. */
 145 +void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[],
 146 +                  FILE *stream)
 147 +@{
 148 +  *ret = fputs(*(char **)args[0], stream);
 149 +@}
 150 +
 151 +int main()
 152 +@{
 153 +  ffi_cif cif;
 154 +  ffi_type *args[1];
 155 +  ffi_closure *closure;
 156 +
 157 +  int (*bound_puts)(char *);
 158 +  int rc;
 159 +
 160 +  /* Allocate closure and bound_puts */
 161 +  closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
 162 +
 163 +  if (closure)
 164 +    @{
 165 +      /* Initialize the argument info vectors */
 166 +      args[0] = &ffi_type_pointer;
 167 +
 168 +      /* Initialize the cif */
 169 +      if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
 170 +                       &ffi_type_uint, args) == FFI_OK)
 171 +        @{
 172 +          /* Initialize the closure, setting stream to stdout */
 173 +          if (ffi_prep_closure_loc(closure, &cif, puts_binding,
 174 +                                   stdout, bound_puts) == FFI_OK)
 175 +            @{
 176 +              rc = bound_puts("Hello World!");
 177 +              /* rc now holds the result of the call to fputs */
 178 +            @}
 179 +        @}
 180 +    @}
 181 +
 182 +  /* Deallocate both closure, and bound_puts */
 183 +  ffi_closure_free(closure);
 184 +
 185 +  return 0;
 186 +@}
 187 +
 188 +@end example
 189 +
 190
 191  @node Missing Features
 192  @chapter Missing Features
 193 @@ -525,6 +580,8 @@ There is no support for bit fields in st
 194  @item
 195  The closure API is
 196
 197 +@c FIXME: ...
 198 +
 199  @item
 200  The ``raw'' API is undocumented.
 201  @c argument promotion?
 202 Index: libffi/ChangeLog.libffi
 203 ===================================================================
 204 --- libffi.orig/ChangeLog.libffi
 205 +++ libffi/ChangeLog.libffi
 206 @@ -1,3 +1,8 @@
 207 +2010-01-12  Conrad Irwin <conrad.irwin@gmail.com>
 208 +
 209 +       * doc/libffi.texi: Add closure example.
 210 +       * doc/libffi.info: Rebuilt.
 211 +
 212  2009-12-25  Samuli Suominen  <ssuominen@gentoo.org>
 213
 214         * configure.ac: Undefine _AC_ARG_VAR_PRECIOUS for autoconf 2.64.