types.rst revision 1.4
1.. Copyright (C) 2014-2018 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:: cpp 19 20Types 21===== 22 23.. class:: gccjit::type 24 25 gccjit::type represents a type within the library. It is a subclass 26 of :class:`gccjit::object`. 27 28Types can be created in several ways: 29 30* fundamental types can be accessed using 31 :func:`gccjit::context::get_type`: 32 33 .. code-block:: c++ 34 35 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); 36 37 or using the :func:`gccjit::context::get_int_type<T>` template: 38 39 .. code-block:: c++ 40 41 gccjit::type t = ctxt.get_int_type <unsigned short> (); 42 43 See :c:func:`gcc_jit_context_get_type` for the available types. 44 45* derived types can be accessed by using functions such as 46 :func:`gccjit::type::get_pointer` and :func:`gccjit::type::get_const`: 47 48 .. code-block:: c++ 49 50 gccjit::type const_int_star = int_type.get_const ().get_pointer (); 51 gccjit::type int_const_star = int_type.get_pointer ().get_const (); 52 53* by creating structures (see below). 54 55Standard types 56-------------- 57 58.. function:: gccjit::type gccjit::context::get_type (enum gcc_jit_types) 59 60 Access a specific type. This is a thin wrapper around 61 :c:func:`gcc_jit_context_get_type`; the parameter has the same meaning. 62 63.. function:: gccjit::type \ 64 gccjit::context::get_int_type (size_t num_bytes, int is_signed) 65 66 Access the integer type of the given size. 67 68.. function:: gccjit::type \ 69 gccjit::context::get_int_type <T> () 70 71 Access the given integer type. For example, you could map the 72 ``unsigned short`` type into a gccjit::type via: 73 74 .. code-block:: c++ 75 76 gccjit::type t = ctxt.get_int_type <unsigned short> (); 77 78Pointers, `const`, and `volatile` 79--------------------------------- 80 81.. function:: gccjit::type gccjit::type::get_pointer () 82 83 Given type "T", get type "T*". 84 85.. function:: gccjit::type gccjit::type::get_const () 86 87 Given type "T", get type "const T". 88 89.. function:: gccjit::type gccjit::type::get_volatile () 90 91 Given type "T", get type "volatile T". 92 93.. function:: gccjit::type gccjit::type::get_aligned (size_t alignment_in_bytes) 94 95 Given type "T", get type: 96 97 .. code-block:: c 98 99 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES))) 100 101 The alignment must be a power of two. 102 103.. function:: gccjit::type \ 104 gccjit::context::new_array_type (gccjit::type element_type, \ 105 int num_elements, \ 106 gccjit::location loc) 107 108 Given type "T", get type "T[N]" (for a constant N). 109 Param "loc" is optional. 110 111 112Vector types 113------------ 114 115.. function:: gccjit::type gccjit::type::get_vector (size_t num_units) 116 117 Given type "T", get type: 118 119 .. code-block:: c 120 121 T __attribute__ ((vector_size (sizeof(T) * num_units)) 122 123 T must be integral or floating point; num_units must be a power of two. 124 125 126Structures and unions 127--------------------- 128 129.. class:: gccjit::struct_ 130 131A compound type analagous to a C `struct`. 132 133:class:`gccjit::struct_` is a subclass of :class:`gccjit::type` (and thus 134of :class:`gccjit::object` in turn). 135 136.. class:: gccjit::field 137 138A field within a :class:`gccjit::struct_`. 139 140:class:`gccjit::field` is a subclass of :class:`gccjit::object`. 141 142You can model C `struct` types by creating :class:`gccjit::struct_` and 143:class:`gccjit::field` instances, in either order: 144 145* by creating the fields, then the structure. For example, to model: 146 147 .. code-block:: c 148 149 struct coord {double x; double y; }; 150 151 you could call: 152 153 .. code-block:: c++ 154 155 gccjit::field field_x = ctxt.new_field (double_type, "x"); 156 gccjit::field field_y = ctxt.new_field (double_type, "y"); 157 std::vector fields; 158 fields.push_back (field_x); 159 fields.push_back (field_y); 160 gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields); 161 162* by creating the structure, then populating it with fields, typically 163 to allow modelling self-referential structs such as: 164 165 .. code-block:: c 166 167 struct node { int m_hash; struct node *m_next; }; 168 169 like this: 170 171 .. code-block:: c++ 172 173 gccjit::struct_ node = ctxt.new_opaque_struct_type ("node"); 174 gccjit::type node_ptr = node.get_pointer (); 175 gccjit::field field_hash = ctxt.new_field (int_type, "m_hash"); 176 gccjit::field field_next = ctxt.new_field (node_ptr, "m_next"); 177 std::vector fields; 178 fields.push_back (field_hash); 179 fields.push_back (field_next); 180 node.set_fields (fields); 181 182.. FIXME: the above API doesn't seem to exist yet 183 184.. function:: gccjit::field \ 185 gccjit::context::new_field (gccjit::type type,\ 186 const char *name, \ 187 gccjit::location loc) 188 189 Construct a new field, with the given type and name. 190 191.. function:: gccjit::struct_ \ 192 gccjit::context::new_struct_type (const std::string &name,\ 193 std::vector<field> &fields,\ 194 gccjit::location loc) 195 196 Construct a new struct type, with the given name and fields. 197 198.. function:: gccjit::struct_ \ 199 gccjit::context::new_opaque_struct (const std::string &name, \ 200 gccjit::location loc) 201 202 Construct a new struct type, with the given name, but without 203 specifying the fields. The fields can be omitted (in which case the 204 size of the struct is not known), or later specified using 205 :c:func:`gcc_jit_struct_set_fields`. 206