diff options
| author | Martin Liska <mliska@suse.cz> | 2022-11-13 21:59:20 +0100 |
|---|---|---|
| committer | Martin Liska <mliska@suse.cz> | 2022-11-14 09:35:06 +0100 |
| commit | 40a39381063fdd83c4cbf5eacebfc50a2201308b (patch) | |
| tree | 1f33224e8587aee59e622085792d4befca0e6d61 /gcc/jit/docs/topics/objects.rst | |
| parent | 64d5610f44c995b88261bf83f53a200355cb530f (diff) | |
| download | gcc-40a39381063fdd83c4cbf5eacebfc50a2201308b.zip gcc-40a39381063fdd83c4cbf5eacebfc50a2201308b.tar.gz gcc-40a39381063fdd83c4cbf5eacebfc50a2201308b.tar.bz2 | |
Revert "sphinx: jit: port libgccjit to shared Sphinx"
This reverts commit 94246daa3efba88d4ae6619f24d737c01ba3dc89.
Diffstat (limited to 'gcc/jit/docs/topics/objects.rst')
| -rw-r--r-- | gcc/jit/docs/topics/objects.rst | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/gcc/jit/docs/topics/objects.rst b/gcc/jit/docs/topics/objects.rst new file mode 100644 index 0000000..42f3675 --- /dev/null +++ b/gcc/jit/docs/topics/objects.rst @@ -0,0 +1,88 @@ +.. Copyright (C) 2014-2022 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 + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Objects +======= + +.. type:: gcc_jit_object + +Almost every entity in the API (with the exception of +:c:expr:`gcc_jit_context *` and :c:expr:`gcc_jit_result *`) is a +"contextual" object, a :c:expr:`gcc_jit_object *` + +A JIT object: + + * is associated with a :c:expr:`gcc_jit_context *`. + + * is automatically cleaned up for you when its context is released so + you don't need to manually track and cleanup all objects, just the + contexts. + +Although the API is C-based, there is a form of class hierarchy, which +looks like this:: + + +- gcc_jit_object + +- gcc_jit_location + +- gcc_jit_type + +- gcc_jit_struct + +- gcc_jit_field + +- gcc_jit_function + +- gcc_jit_block + +- gcc_jit_rvalue + +- gcc_jit_lvalue + +- gcc_jit_param + +- gcc_jit_case + +- gcc_jit_extended_asm + +There are casting methods for upcasting from subclasses to parent classes. +For example, :c:func:`gcc_jit_type_as_object`: + +.. code-block:: c + + gcc_jit_object *obj = gcc_jit_type_as_object (int_type); + +The object "base class" has the following operations: + +.. function:: gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object *obj) + + Which context is "obj" within? + + +.. function:: const char *gcc_jit_object_get_debug_string (gcc_jit_object *obj) + + Generate a human-readable description for the given object. + + For example, + + .. code-block:: c + + printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj)); + + might give this text on stdout: + + .. code-block:: bash + + obj: 4.0 * (float)i + + .. note:: + + If you call this on an object, the `const char *` buffer is allocated + and generated on the first call for that object, and the buffer will + have the same lifetime as the object i.e. it will exist until the + object's context is released. |