[committed] jit: document function pointers
David Malcolm
dmalcolm@redhat.com
Thu Sep 28 17:15:00 GMT 2017
This patch adds a new function-pointers.rst topic page to the libgccjit
docs.
Committed to trunk as r253257.
gcc/jit/ChangeLog:
* docs/topics/expressions.rst (Function calls): Add link to
gcc_jit_context_new_function_ptr_type.
(Function pointers): Convert to cross-references to
function-pointers.rst, moving material there.
* docs/topics/function-pointers.rst: New page.
* docs/topics/index.rst: Add function-pointers.rst.
* docs/topics/types.rst (Function pointer types): New section.
* docs/_build/texinfo/libgccjit.texi: Regenerate.
---
gcc/jit/docs/topics/expressions.rst | 21 ++++----
gcc/jit/docs/topics/function-pointers.rst | 80 +++++++++++++++++++++++++++++++
gcc/jit/docs/topics/index.rst | 1 +
gcc/jit/docs/topics/types.rst | 6 +++
4 files changed, 96 insertions(+), 12 deletions(-)
create mode 100644 gcc/jit/docs/topics/function-pointers.rst
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index f5c2d0f..76aa4eb 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -416,7 +416,8 @@ Function calls
int numargs, \
gcc_jit_rvalue **args)
- Given an rvalue of function pointer type, and the given table of
+ Given an rvalue of function pointer type (e.g. from
+ :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
argument rvalues, construct a call to the function pointer, with the
result as an rvalue.
@@ -452,19 +453,15 @@ Function calls
Function pointers
*****************
-.. function:: gcc_jit_rvalue *\
- gcc_jit_function_get_address (gcc_jit_function *fn,\
- gcc_jit_location *loc)
-
- Get the address of a function as an rvalue, of function pointer
- type.
+Function pointers can be obtained:
- This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test
- for its presence using
-
- .. code-block:: c
+ * from a :c:type:`gcc_jit_function` using
+ :c:func:`gcc_jit_function_get_address`, or
- #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address
+ * from an existing function using
+ :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
+ using a function pointer type obtained using
+ :c:func:`gcc_jit_context_new_function_ptr_type`.
Type-coercion
*************
diff --git a/gcc/jit/docs/topics/function-pointers.rst b/gcc/jit/docs/topics/function-pointers.rst
new file mode 100644
index 0000000..b5b9d1b
--- /dev/null
+++ b/gcc/jit/docs/topics/function-pointers.rst
@@ -0,0 +1,80 @@
+.. Copyright (C) 2017 Free Software Foundation, Inc.
+ Originally contributed by David Malcolm <dmalcolm@redhat.com>
+
+ This is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see
+ <http://www.gnu.org/licenses/>.
+
+.. default-domain:: c
+
+Function pointers
+=================
+
+You can generate calls that use a function pointer via
+:c:func:`gcc_jit_context_new_call_through_ptr`.
+
+To do requires a :c:type:`gcc_jit_rvalue` of the correct function pointer type.
+
+Function pointers for a :c:type:`gcc_jit_function` can be obtained
+via :c:func:`gcc_jit_function_get_address`.
+
+.. function:: gcc_jit_rvalue *\
+ gcc_jit_function_get_address (gcc_jit_function *fn,\
+ gcc_jit_location *loc)
+
+ Get the address of a function as an rvalue, of function pointer
+ type.
+
+ This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test
+ for its presence using
+
+ .. code-block:: c
+
+ #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address
+
+Alternatively, given an existing function, you can obtain a pointer
+to it in :c:type:`gcc_jit_rvalue` form using
+:c:func:`gcc_jit_context_new_rvalue_from_ptr`, using a function pointer
+type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`.
+
+Here's an example of creating a function pointer type corresponding to C's
+:c:type:`void (*) (int, int, int)`:
+
+.. code-block:: c
+
+ gcc_jit_type *void_type =
+ gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID);
+ gcc_jit_type *int_type =
+ gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
+
+ /* Build the function ptr type. */
+ gcc_jit_type *param_types[3];
+ param_types[0] = int_type;
+ param_types[1] = int_type;
+ param_types[2] = int_type;
+
+ gcc_jit_type *fn_ptr_type =
+ gcc_jit_context_new_function_ptr_type (ctxt, NULL,
+ void_type,
+ 3, param_types, 0);
+
+.. function:: gcc_jit_type *\
+ gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt,\
+ gcc_jit_location *loc,\
+ gcc_jit_type *return_type,\
+ int num_params,\
+ gcc_jit_type **param_types,\
+ int is_variadic)
+
+ Generate a :c:type:`gcc_jit_type` for a function pointer with the
+ given return type and parameters.
diff --git a/gcc/jit/docs/topics/index.rst b/gcc/jit/docs/topics/index.rst
index 890f21c..a912a6d 100644
--- a/gcc/jit/docs/topics/index.rst
+++ b/gcc/jit/docs/topics/index.rst
@@ -26,6 +26,7 @@ Topic Reference
types.rst
expressions.rst
functions.rst
+ function-pointers.rst
locations.rst
compilation.rst
compatibility.rst
diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst
index c279222..35a8231 100644
--- a/gcc/jit/docs/topics/types.rst
+++ b/gcc/jit/docs/topics/types.rst
@@ -309,3 +309,9 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and
:start-after: /* Quote from here in docs/topics/types.rst. */
:end-before: /* Quote up to here in docs/topics/types.rst. */
:language: c
+
+Function pointer types
+----------------------
+
+Function pointer types can be created using
+:c:func:`gcc_jit_context_new_function_ptr_type`.
--
1.8.5.3
More information about the Gcc-patches
mailing list