Document libgccjit++.h

[thirdparty/gcc.git] / gcc / jit / docs / cp / topics / contexts.rst

.. Copyright (C) 2014 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
   <http://www.gnu.org/licenses/>.

.. default-domain:: cpp

Compilation contexts
====================

.. class:: gccjit::context

The top-level of the C++ API is the :class:`gccjit::context` type.

A :class:`gccjit::context` instance encapsulates the state of a
compilation.

You can set up options on it, and add types, functions and code.
Invoking :func:`gccjit::context::compile` on it gives you a
:c:type:`gcc_jit_result *`.

It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.

Lifetime-management
-------------------
Contexts are the unit of lifetime-management within the API: objects
have their lifetime bounded by the context they are created within, and
cleanup of such objects is done for you when the context is released.

.. function:: gccjit::context gccjit::context::acquire ()

  This function acquires a new :class:`gccjit::context` instance,
  which is independent of any others that may be present within this
  process.

.. function:: void gccjit::context::release ()

  This function releases all resources associated with the given context.
  Both the context itself and all of its :c:type:`gccjit::object *`
  instances are cleaned up.  It should be called exactly once on a given
  context.

  It is invalid to use the context or any of its "contextual" objects
  after calling this.

  .. code-block:: c++

    ctxt.release ();

.. function:: gccjit::context \
              gccjit::context::new_child_context ()

   Given an existing JIT context, create a child context.

   The child inherits a copy of all option-settings from the parent.

   The child can reference objects created within the parent, but not
   vice-versa.

   The lifetime of the child context must be bounded by that of the
   parent: you should release a child context before releasing the parent
   context.

   If you use a function from a parent context within a child context,
   you have to compile the parent context before you can compile the
   child context, and the gccjit::result of the parent context must
   outlive the gccjit::result of the child context.

   This allows caching of shared initializations.  For example, you could
   create types and declarations of global functions in a parent context
   once within a process, and then create child contexts whenever a
   function or loop becomes hot. Each such child context can be used for
   JIT-compiling just one function or loop, but can reference types
   and helper functions created within the parent context.

   Contexts can be arbitrarily nested, provided the above rules are
   followed, but it's probably not worth going above 2 or 3 levels, and
   there will likely be a performance hit for such nesting.


Thread-safety
-------------
Instances of :class:`gccjit::context` created via
:func:`gccjit::context::acquire` are independent from each other:
only one thread may use a given context at once, but multiple threads
could each have their own contexts without needing locks.

Contexts created via :func:`gccjit::context::new_child_context` are
related to their parent context.  They can be partitioned by their
ultimate ancestor into independent "family trees".   Only one thread
within a process may use a given "family tree" of such contexts at once,
and if you're using multiple threads you should provide your own locking
around entire such context partitions.


Error-handling
--------------
.. FIXME: How does error-handling work for C++ API?

You can only compile and get code from a context if no errors occur.

In general, if an error occurs when using an API entrypoint, it returns
NULL.  You don't have to check everywhere for NULL results, since the
API gracefully handles a NULL being passed in for any argument.

Errors are printed on stderr and can be queried using
:func:`gccjit::context::get_first_error`.

.. function:: const char *\
              gccjit::context::get_first_error (gccjit::context *ctxt)

   Returns the first error message that occurred on the context.

   The returned string is valid for the rest of the lifetime of the
   context.

   If no errors occurred, this will be NULL.

Debugging
---------

.. function:: void\
              gccjit::context::dump_to_file (const std::string &path, \
                                             int update_locations)

   To help with debugging: dump a C-like representation to the given path,
   describing what's been set up on the context.

   If "update_locations" is true, then also set up :class:`gccjit::location`
   information throughout the context, pointing at the dump file as if it
   were a source file.  This may be of use in conjunction with
   :c:macro:`GCCJIT::BOOL_OPTION_DEBUGINFO` to allow stepping through the
   code in a debugger.


Options
-------

..
  FIXME: gccjit::context::set_str_option doesn't seem to exist yet in the
  C++ API

Boolean options
***************

.. function:: void \
              gccjit::context::set_bool_option(enum gcc_jit_bool_option, \
                                               int value)

  Set a boolean option of the context.

  This is a thin wrapper around the C API
  :c:func:`gcc_jit_context_set_bool_option`; the options have the same
  meaning.

Integer options
***************

.. function:: void \
              gccjit::context::set_int_option (enum gcc_jit_int_option, \
                                               int value)

  Set an integer option of the context.

  This is a thin wrapper around the C API
  :c:func:`gcc_jit_context_set_int_option`; the options have the same
  meaning.