objects.rst revision 1.5
1.. Copyright (C) 2014-2019 Free Software Foundation, Inc. 2 Originally contributed by David Malcolm <dmalcolm@redhat.com> 3 4 This is free software: you can redistribute it and/or modify it 5 under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 3 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, but 10 WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see 16 <http://www.gnu.org/licenses/>. 17 18.. default-domain:: c 19 20Objects 21======= 22 23.. type:: gcc_jit_object 24 25Almost every entity in the API (with the exception of 26:c:type:`gcc_jit_context *` and :c:type:`gcc_jit_result *`) is a 27"contextual" object, a :c:type:`gcc_jit_object *` 28 29A JIT object: 30 31 * is associated with a :c:type:`gcc_jit_context *`. 32 33 * is automatically cleaned up for you when its context is released so 34 you don't need to manually track and cleanup all objects, just the 35 contexts. 36 37Although the API is C-based, there is a form of class hierarchy, which 38looks like this:: 39 40 +- gcc_jit_object 41 +- gcc_jit_location 42 +- gcc_jit_type 43 +- gcc_jit_struct 44 +- gcc_jit_field 45 +- gcc_jit_function 46 +- gcc_jit_block 47 +- gcc_jit_rvalue 48 +- gcc_jit_lvalue 49 +- gcc_jit_param 50 +- gcc_jit_case 51 52There are casting methods for upcasting from subclasses to parent classes. 53For example, :c:func:`gcc_jit_type_as_object`: 54 55.. code-block:: c 56 57 gcc_jit_object *obj = gcc_jit_type_as_object (int_type); 58 59The object "base class" has the following operations: 60 61.. function:: gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object *obj) 62 63 Which context is "obj" within? 64 65 66.. function:: const char *gcc_jit_object_get_debug_string (gcc_jit_object *obj) 67 68 Generate a human-readable description for the given object. 69 70 For example, 71 72 .. code-block:: c 73 74 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj)); 75 76 might give this text on stdout: 77 78 .. code-block:: bash 79 80 obj: 4.0 * (float)i 81 82 .. note:: 83 84 If you call this on an object, the `const char *` buffer is allocated 85 and generated on the first call for that object, and the buffer will 86 have the same lifetime as the object i.e. it will exist until the 87 object's context is released. 88