-.. Copyright (C) 2014 Free Software Foundation, Inc.
+.. Copyright (C) 2014-2020 Free Software Foundation, Inc.
Originally contributed by David Malcolm <dmalcolm@redhat.com>
This is free software: you can redistribute it and/or modify it
int value)
Given a numeric type (integer or floating point), build an rvalue for
- the given constant value.
+ the given constant :c:type:`int` value.
+
+.. function:: gcc_jit_rvalue *\
+ gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
+ gcc_jit_type *numeric_type, \
+ long value)
+
+ Given a numeric type (integer or floating point), build an rvalue for
+ the given constant :c:type:`long` value.
.. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
gcc_jit_type *numeric_type)
gcc_jit_type *numeric_type)
Given a numeric type (integer or floating point), get the rvalue for
- zero. Essentially this is just a shortcut for:
+ one. Essentially this is just a shortcut for:
.. code-block:: c
double value)
Given a numeric type (integer or floating point), build an rvalue for
- the given constant value.
+ the given constant :c:type:`double` value.
.. function:: gcc_jit_rvalue *\
gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
Generate an rvalue for the given NIL-terminated string, of type
:c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.
+ The parameter ``value`` must be non-NULL. The call takes a copy of the
+ underlying string, so it is valid to pass in a pointer to an on-stack
+ buffer.
+
+Vector expressions
+******************
+
+.. function:: gcc_jit_rvalue * \
+ gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
+ gcc_jit_location *loc, \
+ gcc_jit_type *vec_type, \
+ size_t num_elements, \
+ gcc_jit_rvalue **elements)
+
+ Build a vector rvalue from an array of elements.
+
+ "vec_type" should be a vector type, created using
+ :func:`gcc_jit_type_get_vector`.
+
+ "num_elements" should match that of the vector type.
+
+ This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
+ its presence using
+
+ .. code-block:: c
+
+ #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
Unary Operations
****************
:c:macro:`GCC_JIT_UNARY_OP_MINUS` `-(EXPR)`
:c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` `~(EXPR)`
:c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` `!(EXPR)`
+:c:macro:`GCC_JIT_UNARY_OP_ABS` `abs (EXPR)`
========================================== ============
.. c:macro:: GCC_JIT_UNARY_OP_MINUS
in C.
+.. c:macro:: GCC_JIT_UNARY_OP_ABS
+
+ Absolute value of an arithmetic expression; analogous to:
+
+ .. code-block:: c
+
+ abs (EXPR)
+
+ in C.
+
Binary Operations
*****************
For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
-.. c:macro:: GCC_JIT_BINARY_OP_MINUS`
+.. c:macro:: GCC_JIT_BINARY_OP_MINUS
Subtraction of arithmetic values; analogous to:
printf_func,
2, args));
+.. function:: gcc_jit_rvalue *\
+ gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
+ gcc_jit_location *loc,\
+ gcc_jit_rvalue *fn_ptr,\
+ int numargs, \
+ gcc_jit_rvalue **args)
+
+ 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.
+
+ .. note::
+
+ The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
+
+.. function:: void\
+ gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
+ int require_tail_call)
+
+ Given an :c:type:`gcc_jit_rvalue *` for a call created through
+ :c:func:`gcc_jit_context_new_call` or
+ :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
+ call as needing tail-call optimization. The optimizer will
+ attempt to optimize the call into a jump instruction; if it is
+ unable to do do, an error will be emitted.
+
+ This may be useful when implementing functions that use the
+ continuation-passing style (e.g. for functional programming
+ languages), in which every function "returns" by calling a
+ "continuation" function pointer. This call must be
+ guaranteed to be implemented as a jump, otherwise the program
+ could consume an arbitrary amount of stack space as it executed.
+
+ This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
+ its presence using
+
+ .. code-block:: c
+
+ #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
+
+Function pointers
+*****************
+
+Function pointers can be obtained:
+
+ * from a :c:type:`gcc_jit_function` using
+ :c:func:`gcc_jit_function_get_address`, or
+
+ * 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
*************
.. function:: gcc_jit_lvalue *\
gcc_jit_context_new_global (gcc_jit_context *ctxt,\
gcc_jit_location *loc,\
+ enum gcc_jit_global_kind kind,\
gcc_jit_type *type,\
const char *name)
Add a new global variable of the given type and name to the context.
+ The parameter ``name`` must be non-NULL. The call takes a copy of the
+ underlying string, so it is valid to pass in a pointer to an on-stack
+ buffer.
+
+ The "kind" parameter determines the visibility of the "global" outside
+ of the :c:type:`gcc_jit_result`:
+
+ .. type:: enum gcc_jit_global_kind
+
+ .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
+
+ Global is defined by the client code and is visible
+ by name outside of this JIT context via
+ :c:func:`gcc_jit_result_get_global` (and this value is required for
+ the global to be accessible via that entrypoint).
+
+ .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
+
+ Global is defined by the client code, but is invisible
+ outside of it. Analogous to a "static" global within a .c file.
+ Specifically, the variable will only be visible within this
+ context and within child contexts.
+
+ .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
+
+ Global is not defined by the client code; we're merely
+ referring to it. Analogous to using an "extern" global from a
+ header file.
Working with pointers, structs and unions
-----------------------------------------