Patchwork [libffi] Add closure example documentation

login
register
mail settings
Submitter Anthony Green
Date Aug. 6, 2010, 4:46 a.m.
Message ID <m3hbj82vr4.fsf@redhat.com>
Download mbox | patch
Permalink /patch/61062/
State New
Headers show

Comments

Anthony Green - Aug. 6, 2010, 4:46 a.m.
I'm checking in the following libffi patch.  

This patch from Conrad Irwin adds an example to the documentation.


2010-01-12  Conrad Irwin <conrad.irwin@gmail.com>

	* doc/libffi.texi: Add closure example.

Patch

Index: libffi/doc/libffi.texi
===================================================================
--- libffi.orig/doc/libffi.texi
+++ libffi/doc/libffi.texi
@@ -19,7 +19,7 @@ 
 This manual is for Libffi, a portable foreign-function interface
 library.
 
-Copyright @copyright{} 2008 Red Hat, Inc.
+Copyright @copyright{} 2008, 2010 Red Hat, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -106,6 +106,7 @@  values passed between the two languages.
 * Types::                       libffi type descriptions.
 * Multiple ABIs::               Different passing styles on one platform.
 * The Closure API::             Writing a generic function.
+* Closure Example::             A closure example.
 @end menu
 
 
@@ -500,12 +501,66 @@  After calling @code{ffi_prep_closure_loc
 to the appropriate pointer-to-function type.
 @end defun
 
-@c FIXME: example
-
 You may see old code referring to @code{ffi_prep_closure}.  This
 function is deprecated, as it cannot handle the need for separate
 writable and executable addresses.
 
+@node Closure Example
+@section Closure Example
+
+A trivial example that creates a new @code{puts} by binding 
+@code{fputs} with @code{stdin}.
+
+@example
+#include <stdio.h>
+#include <ffi.h>
+
+/* Acts like puts with the file given at time of enclosure. */
+void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], 
+                  FILE *stream)
+@{
+  *ret = fputs(*(char **)args[0], stream);
+@}
+
+int main()
+@{
+  ffi_cif cif;
+  ffi_type *args[1];
+  ffi_closure *closure;
+
+  int (*bound_puts)(char *);
+  int rc;
+  
+  /* Allocate closure and bound_puts */
+  closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
+
+  if (closure)
+    @{
+      /* Initialize the argument info vectors */
+      args[0] = &ffi_type_pointer;
+
+      /* Initialize the cif */
+      if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
+                       &ffi_type_uint, args) == FFI_OK)
+        @{
+          /* Initialize the closure, setting stream to stdout */
+          if (ffi_prep_closure_loc(closure, &cif, puts_binding, 
+                                   stdout, bound_puts) == FFI_OK)
+            @{
+              rc = bound_puts("Hello World!");
+              /* rc now holds the result of the call to fputs */
+            @}
+        @}
+    @}
+
+  /* Deallocate both closure, and bound_puts */
+  ffi_closure_free(closure);
+
+  return 0;
+@}
+
+@end example
+
 
 @node Missing Features
 @chapter Missing Features
@@ -525,6 +580,8 @@  There is no support for bit fields in st
 @item
 The closure API is
 
+@c FIXME: ...
+
 @item
 The ``raw'' API is undocumented.
 @c argument promotion?