]>
Commit | Line | Data |
---|---|---|
99dee823 | 1 | .. Copyright (C) 2014-2021 Free Software Foundation, Inc. |
29df5715 DM |
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 | ||
20 | Types | |
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 | ||
28 | Types 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 | ||
55 | Standard 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 | ||
78 | Pointers, `const`, and `volatile` | |
79 | --------------------------------- | |
80 | ||
81 | .. function:: gccjit::type gccjit::type::get_pointer () | |
82 | ||
83 | Given type "T", get type "T*". | |
84 | ||
29df5715 DM |
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 | ||
0ebd1f00 DM |
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 | ||
29df5715 DM |
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 | ||
47ee1b7c DM |
112 | Vector 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 | ||
29df5715 DM |
126 | Structures and unions |
127 | --------------------- | |
128 | ||
129 | .. class:: gccjit::struct_ | |
130 | ||
131 | A compound type analagous to a C `struct`. | |
132 | ||
133 | :class:`gccjit::struct_` is a subclass of :class:`gccjit::type` (and thus | |
134 | of :class:`gccjit::object` in turn). | |
135 | ||
136 | .. class:: gccjit::field | |
137 | ||
138 | A field within a :class:`gccjit::struct_`. | |
139 | ||
140 | :class:`gccjit::field` is a subclass of :class:`gccjit::object`. | |
141 | ||
142 | You 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`. |