1#@!#!123s

: / usr / share / doc / libffi-dev / html /
Filename : The-Closure-API.html
back
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- 
This manual is for libffi, a portable foreign function interface
library.

Copyright © 2008-2024 Anthony Green and Red Hat, Inc.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 -->
<title>The Closure API (libffi: the portable foreign function interface library)</title>

<meta name="description" content="The Closure API (libffi: the portable foreign function interface library)">
<meta name="keywords" content="The Closure API (libffi: the portable foreign function interface library)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Index.html" rel="index" title="Index">
<link href="Using-libffi.html" rel="up" title="Using libffi">
<link href="Closure-Example.html" rel="next" title="Closure Example">
<link href="Multiple-ABIs.html" rel="prev" title="Multiple ABIs">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en">
<div class="section-level-extent" id="The-Closure-API">
<div class="nav-panel">
<p>
Next: <a href="Closure-Example.html" accesskey="n" rel="next">Closure Example</a>, Previous: <a href="Multiple-ABIs.html" accesskey="p" rel="prev">Multiple ABIs</a>, Up: <a href="Using-libffi.html" accesskey="u" rel="up">Using libffi</a> &nbsp; [<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="The-Closure-API-1"><span>2.5 The Closure API<a class="copiable-link" href="#The-Closure-API-1"> &para;</a></span></h3>

<p><code class="code">libffi</code> also provides a way to write a generic function &ndash; a
function that can accept and decode any combination of arguments.
This can be useful when writing an interpreter, or to provide wrappers
for arbitrary functions.
</p>
<p>This facility is called the <em class="dfn">closure API</em>.  Closures are not
supported on all platforms; you can check the <code class="code">FFI_CLOSURES</code>
define to determine whether they are supported on the current
platform.
<a class="index-entry-id" id="index-closures"></a>
<a class="index-entry-id" id="index-closure-API"></a>
<a class="index-entry-id" id="index-FFI_005fCLOSURES"></a>
</p>
<p>Because closures work by assembling a tiny function at runtime, they
require special allocation on platforms that have a non-executable
heap.  Memory management for closures is handled by a pair of
functions:
</p>
<a class="index-entry-id" id="index-ffi_005fclosure_005falloc"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-void-1"><span class="category-def">Function: </span><span><strong class="def-name">void</strong> <var class="def-var-arguments">*ffi_closure_alloc (size_t <var class="var">size</var>, void **<var class="var">code</var>)</var><a class="copiable-link" href="#index-void-1"> &para;</a></span></dt>
<dd><p>Allocate a chunk of memory holding <var class="var">size</var> bytes.  This returns a
pointer to the writable address, and sets *<var class="var">code</var> to the
corresponding executable address.
</p>
<p><var class="var">size</var> should be sufficient to hold a <code class="code">ffi_closure</code> object.
</p></dd></dl>

<a class="index-entry-id" id="index-ffi_005fclosure_005ffree"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-void-2"><span class="category-def">Function: </span><span><strong class="def-name">void</strong> <var class="def-var-arguments">ffi_closure_free (void *<var class="var">writable</var>)</var><a class="copiable-link" href="#index-void-2"> &para;</a></span></dt>
<dd><p>Free memory allocated using <code class="code">ffi_closure_alloc</code>.  The argument is
the writable address that was returned.
</p></dd></dl>

<p>Once you have allocated the memory for a closure, you must construct a
<code class="code">ffi_cif</code> describing the function call.  Finally you can prepare
the closure function:
</p>
<a class="index-entry-id" id="index-ffi_005fprep_005fclosure_005floc"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ffi_005fstatus-3"><span class="category-def">Function: </span><span><strong class="def-name">ffi_status</strong> <var class="def-var-arguments">ffi_prep_closure_loc (ffi_closure *<var class="var">closure</var>, ffi_cif *<var class="var">cif</var>, void (*<var class="var">fun</var>) (ffi_cif *<var class="var">cif</var>, void *<var class="var">ret</var>, void **<var class="var">args</var>, void *<var class="var">user_data</var>), void *<var class="var">user_data</var>, void *<var class="var">codeloc</var>)</var><a class="copiable-link" href="#index-ffi_005fstatus-3"> &para;</a></span></dt>
<dd><p>Prepare a closure function.  The arguments to
<code class="code">ffi_prep_closure_loc</code> are:
</p>
<dl class="table">
<dt><var class="var">closure</var></dt>
<dd><p>The address of a <code class="code">ffi_closure</code> object; this is the writable
address returned by <code class="code">ffi_closure_alloc</code>.
</p>
</dd>
<dt><var class="var">cif</var></dt>
<dd><p>The <code class="code">ffi_cif</code> describing the function parameters.  Note that this
object, and the types to which it refers, must be kept alive until the
closure itself is freed.
</p>
</dd>
<dt><var class="var">user_data</var></dt>
<dd><p>An arbitrary datum that is passed, uninterpreted, to your closure
function.
</p>
</dd>
<dt><var class="var">codeloc</var></dt>
<dd><p>The executable address returned by <code class="code">ffi_closure_alloc</code>.
</p>
</dd>
<dt><var class="var">fun</var></dt>
<dd><p>The function which will be called when the closure is invoked.  It is
called with the arguments:
</p>
<dl class="table">
<dt><var class="var">cif</var></dt>
<dd><p>The <code class="code">ffi_cif</code> passed to <code class="code">ffi_prep_closure_loc</code>.
</p>
</dd>
<dt><var class="var">ret</var></dt>
<dd><p>A pointer to the memory used for the function&rsquo;s return value.
</p>
<p>If the function is declared as returning <code class="code">void</code>, then this value
is garbage and should not be used.
</p>
<p>Otherwise, <var class="var">fun</var> must fill the object to which this points,
following the same special promotion behavior as <code class="code">ffi_call</code>.
That is, in most cases, <var class="var">ret</var> points to an object of exactly the
size of the type specified when <var class="var">cif</var> was constructed.  However,
integral types narrower than the system register size are widened.  In
these cases your program may assume that <var class="var">ret</var> points to an
<code class="code">ffi_arg</code> object.
</p>
</dd>
<dt><var class="var">args</var></dt>
<dd><p>A vector of pointers to memory holding the arguments to the function.
</p>
</dd>
<dt><var class="var">user_data</var></dt>
<dd><p>The same <var class="var">user_data</var> that was passed to
<code class="code">ffi_prep_closure_loc</code>.
</p></dd>
</dl>
</dd>
</dl>

<p><code class="code">ffi_prep_closure_loc</code> will return <code class="code">FFI_OK</code> if everything
went ok, and one of the other <code class="code">ffi_status</code> values on error.
</p>
<p>After calling <code class="code">ffi_prep_closure_loc</code>, you can cast <var class="var">codeloc</var>
to the appropriate pointer-to-function type.
</p></dd></dl>

<p>You may see old code referring to <code class="code">ffi_prep_closure</code>.  This
function is deprecated, as it cannot handle the need for separate
writable and executable addresses.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Closure-Example.html">Closure Example</a>, Previous: <a href="Multiple-ABIs.html">Multiple ABIs</a>, Up: <a href="Using-libffi.html">Using libffi</a> &nbsp; [<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>