1.. Copyright (C) 2014-2016 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
20Compilation contexts
21====================
22
23.. class:: gccjit::context
24
25The top-level of the C++ API is the :class:`gccjit::context` type.
26
27A :class:`gccjit::context` instance encapsulates the state of a
28compilation.
29
30You can set up options on it, and add types, functions and code.
31Invoking :func:`gccjit::context::compile` on it gives you a
32:c:type:`gcc_jit_result *`.
33
34It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.
35
36Lifetime-management
37-------------------
38Contexts are the unit of lifetime-management within the API: objects
39have their lifetime bounded by the context they are created within, and
40cleanup of such objects is done for you when the context is released.
41
42.. function:: gccjit::context gccjit::context::acquire ()
43
44  This function acquires a new :class:`gccjit::context` instance,
45  which is independent of any others that may be present within this
46  process.
47
48.. function:: void gccjit::context::release ()
49
50  This function releases all resources associated with the given context.
51  Both the context itself and all of its :c:type:`gccjit::object *`
52  instances are cleaned up.  It should be called exactly once on a given
53  context.
54
55  It is invalid to use the context or any of its "contextual" objects
56  after calling this.
57
58  .. code-block:: c++
59
60    ctxt.release ();
61
62.. function:: gccjit::context \
63              gccjit::context::new_child_context ()
64
65   Given an existing JIT context, create a child context.
66
67   The child inherits a copy of all option-settings from the parent.
68
69   The child can reference objects created within the parent, but not
70   vice-versa.
71
72   The lifetime of the child context must be bounded by that of the
73   parent: you should release a child context before releasing the parent
74   context.
75
76   If you use a function from a parent context within a child context,
77   you have to compile the parent context before you can compile the
78   child context, and the gccjit::result of the parent context must
79   outlive the gccjit::result of the child context.
80
81   This allows caching of shared initializations.  For example, you could
82   create types and declarations of global functions in a parent context
83   once within a process, and then create child contexts whenever a
84   function or loop becomes hot. Each such child context can be used for
85   JIT-compiling just one function or loop, but can reference types
86   and helper functions created within the parent context.
87
88   Contexts can be arbitrarily nested, provided the above rules are
89   followed, but it's probably not worth going above 2 or 3 levels, and
90   there will likely be a performance hit for such nesting.
91
92
93Thread-safety
94-------------
95Instances of :class:`gccjit::context` created via
96:func:`gccjit::context::acquire` are independent from each other:
97only one thread may use a given context at once, but multiple threads
98could each have their own contexts without needing locks.
99
100Contexts created via :func:`gccjit::context::new_child_context` are
101related to their parent context.  They can be partitioned by their
102ultimate ancestor into independent "family trees".   Only one thread
103within a process may use a given "family tree" of such contexts at once,
104and if you're using multiple threads you should provide your own locking
105around entire such context partitions.
106
107
108Error-handling
109--------------
110.. FIXME: How does error-handling work for C++ API?
111
112You can only compile and get code from a context if no errors occur.
113
114In general, if an error occurs when using an API entrypoint, it returns
115NULL.  You don't have to check everywhere for NULL results, since the
116API gracefully handles a NULL being passed in for any argument.
117
118Errors are printed on stderr and can be queried using
119:func:`gccjit::context::get_first_error`.
120
121.. function:: const char *\
122              gccjit::context::get_first_error (gccjit::context *ctxt)
123
124   Returns the first error message that occurred on the context.
125
126   The returned string is valid for the rest of the lifetime of the
127   context.
128
129   If no errors occurred, this will be NULL.
130
131Debugging
132---------
133
134.. function:: void\
135              gccjit::context::dump_to_file (const std::string &path, \
136                                             int update_locations)
137
138   To help with debugging: dump a C-like representation to the given path,
139   describing what's been set up on the context.
140
141   If "update_locations" is true, then also set up :class:`gccjit::location`
142   information throughout the context, pointing at the dump file as if it
143   were a source file.  This may be of use in conjunction with
144   :c:macro:`GCCJIT::BOOL_OPTION_DEBUGINFO` to allow stepping through the
145   code in a debugger.
146
147.. function:: void\
148              gccjit::context::dump_reproducer_to_file (gcc_jit_context *ctxt,\
149                                                        const char *path)
150
151   This is a thin wrapper around the C API
152   :c:func:`gcc_jit_context_dump_reproducer_to_file`, and hence works the
153   same way.
154
155   Note that the generated source is C code, not C++; this might be of use
156   for seeing what the C++ bindings are doing at the C level.
157
158Options
159-------
160
161String Options
162**************
163
164.. function:: void \
165              gccjit::context::set_str_option (enum gcc_jit_str_option, \
166                                               const char *value)
167
168   Set a string option of the context.
169
170   This is a thin wrapper around the C API
171   :c:func:`gcc_jit_context_set_str_option`; the options have the same
172   meaning.
173
174Boolean options
175***************
176
177.. function:: void \
178              gccjit::context::set_bool_option(enum gcc_jit_bool_option, \
179                                               int value)
180
181  Set a boolean option of the context.
182
183  This is a thin wrapper around the C API
184  :c:func:`gcc_jit_context_set_bool_option`; the options have the same
185  meaning.
186
187.. function:: void \
188              gccjit::context::set_bool_allow_unreachable_blocks (int bool_value)
189
190   By default, libgccjit will issue an error about unreachable blocks
191   within a function.
192
193   This entrypoint can be used to disable that error; it is a thin wrapper
194   around the C API
195   :c:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`.
196
197   This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for
198   its presence using
199
200   .. code-block:: c
201
202      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
203
204.. function:: void \
205              gccjit::context::set_bool_use_external_driver (int bool_value)
206
207   libgccjit internally generates assembler, and uses "driver" code
208   for converting it to other formats (e.g. shared libraries).
209
210   By default, libgccjit will use an embedded copy of the driver
211   code.
212
213   This option can be used to instead invoke an external driver executable
214   as a subprocess; it is a thin wrapper around the C API
215   :c:func:`gcc_jit_context_set_bool_use_external_driver`.
216
217   This entrypoint was added in :ref:`LIBGCCJIT_ABI_5`; you can test for
218   its presence using
219
220   .. code-block:: c
221
222      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
223
224Integer options
225***************
226
227.. function:: void \
228              gccjit::context::set_int_option (enum gcc_jit_int_option, \
229                                               int value)
230
231  Set an integer option of the context.
232
233  This is a thin wrapper around the C API
234  :c:func:`gcc_jit_context_set_int_option`; the options have the same
235  meaning.
236
237Additional command-line options
238*******************************
239
240.. function:: void \
241              gccjit::context::add_command_line_option (const char *optname)
242
243   Add an arbitrary gcc command-line option to the context for use
244   when compiling.
245
246   This is a thin wrapper around the C API
247   :c:func:`gcc_jit_context_add_command_line_option`.
248
249   This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for
250   its presence using
251
252   .. code-block:: c
253
254      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
255