view release on metacpan or  search on metacpan

libjit/doc/libjit.texi  view on Meta::CPAN

To force the function to be recompiled you need to build it again
and call @code{jit_function_compile} after that.  As always when
the function is built and compiled manually it is necessary
to take care of context locking:

@example
jit_context_build_start(context);
jit_function_get_on_demand_compiler(function)(function);
jit_function_compile(function);
jit_context_build_end(context);
@end example

After this, any existing references to the function will be redirected
to the new version.  However, if some thread is currently executing the
previous version, then it will keep doing so until the previous version
exits.  Only after that will subsequent calls go to the new version.

In this tutorial, we use the same on-demand compiler when we
recompile @code{mul_add}.  In a real program, you would probably call
@code{jit_function_set_on_demand_compiler} to set a new on-demand
compiler that performs greater levels of optimization.

If you no longer intend to recompile the function, you should call
@code{jit_function_clear_recompilable} so that @code{libjit} can
manage the function more efficiently from then on.

The exact conditions under which a function should be recompiled
are not specified by @code{libjit}.  It may be because the function
has been called several times and has reached some threshold.
Or it may be because some other function that it calls has become a
candidate for inlining.  It is up to the front end to decide when
recompilation is warranted, usually based on language-specific
heuristics.

@c -----------------------------------------------------------------------

@node Tutorial 4, Tutorial 5, Tutorial 3, Tutorials
@section Tutorial 4 - mul_add, C++ version
@cindex mul_add C++ tutorial

While @code{libjit} can be easily accessed from C++ programs using
the C API's, you may instead wish to use an API that better reflects
the C++ programming paradigm.  We demonstrate how to do this by rewriting
Tutorial 3 using the @code{libjitplus} library.

@noindent
To use the @code{libjitplus} library, we first include
the @code{<jit/jit-plus.h>} file:

@example
#include <jit/jit-plus.h>
@end example

This file incorporates all of the definitions from @code{<jit/jit.h>},
so you have full access to the underlying C API if you need it.

This time, instead of building the @code{mul_add} function with
@code{jit_function_create} and friends, we define a class to represent it:

@example
class mul_add_function : public jit_function
@{
public:
    mul_add_function(jit_context& context) : jit_function(context)
    @{
        create();
        set_recompilable();
    @}

    virtual void build();

protected:
    virtual jit_type_t create_signature();
@};
@end example

Where we used @code{jit_function_t} and @code{jit_context_t} before,
we now use the C++ @code{jit_function} and @code{jit_context} classes.

In our constructor, we attach ourselves to the context and then call
the @code{create()} method.  This is in turn will call our overridden
virtual method @code{create_signature()} to obtain the signature:

@example
jit_type_t mul_add_function::create_signature()
@{
    // Return type, followed by three parameters,
    // terminated with "end_params".
    return signature_helper
        (jit_type_int, jit_type_int, jit_type_int,
         jit_type_int, end_params);
@}
@end example

The @code{signature_helper()} method is provided for your convenience,
to help with building function signatures.  You can create your own
signature manually using @code{jit_type_create_signature} if you wish.

The final thing we do in the constructor is call @code{set_recompilable()}
to mark the @code{mul_add} function as recompilable, just as we did in
Tutorial 3.

The C++ library will create the function as compilable on-demand for
us, so we don't have to do that explicitly.  But we do have to override
the virtual @code{build()} method to build the function's body on-demand:

@example
void mul_add_function::build()
@{
    jit_value x = get_param(0);
    jit_value y = get_param(1);
    jit_value z = get_param(2);

    insn_return(x * y + z);
@}
@end example

This is similar to the first version that we wrote in Tutorial 1.
Instructions are created with @code{insn_*} methods that correspond
to their @code{jit_insn_*} counterparts in the C library.

One of the nice things about the C++ API compared to the C API is that we
can use overloaded operators to manipulate @code{jit_value} objects.

libjit/doc/libjit.texi  view on Meta::CPAN

@cindex Diagnostic routines

@include libjitext-dump.texi

@c -----------------------------------------------------------------------

@node C++ Interface, C++ Contexts, Diagnostic Routines, Top
@chapter Using libjit from C++
@cindex Using libjit from C++

This chapter describes the classes and methods that are available
in the @code{libjitplus} library.  To use this library, you must
include the header @code{<jit/jit-plus.h>} and link with the
@code{-ljitplus} and @code{-ljit} options.

@menu
* C++ Contexts::            Contexts in C++
* C++ Values::              Values in C++
* C++ Functions::           Functions in C++
@end menu

@c -----------------------------------------------------------------------

@node C++ Contexts, C++ Values, C++ Interface, C++ Interface
@chapter Contexts in C++
@cindex C++ contexts

@include libjitext-plus-context.texi

@c -----------------------------------------------------------------------

@node C++ Values, C++ Functions, C++ Contexts, C++ Interface
@chapter Values in C++
@cindex C++ values

@include libjitext-plus-value.texi

@c -----------------------------------------------------------------------

@node C++ Functions, Porting, C++ Values, C++ Interface
@chapter Functions in C++
@cindex C++ functions

@include libjitext-plus-function.texi

@c -----------------------------------------------------------------------

@node Porting, Porting Apply, C++ Functions, Top
@chapter Porting libjit to new architectures
@cindex Porting libjit

This chapter describes what needs to be done to port @code{libjit}
to a new CPU architecture.  It is assumed that the reader is familiar
with compiler implementation techniques and the particulars of their
target CPU's instruction set.

We will use @code{ARCH} to represent the name of the architecture
in the sections that follow.  It is usually the name of the CPU in
lower case (e.g. @code{x86}, @code{arm}, @code{ppc}, etc).  By
convention, all back end functions should be prefixed with @code{_jit},
because they are not part of the public API.

@menu
* Porting Apply::           Porting the function apply facility
* Instruction Generation::  Creating the instruction generation macros
* Architecture Rules::      Writing the architecture definition rules
* Register Allocation::     Allocating registers in the back end
@end menu

@c -----------------------------------------------------------------------

@node Porting Apply, Instruction Generation, Porting, Porting
@section Porting the function apply facility
@cindex Porting apply

The first step in porting @code{libjit} to a new architecture is to port
the @code{jit_apply} facility.  This provides support for calling
arbitrary C functions from your application or from JIT'ed code.
If you are familiar with @code{libffi} or @code{ffcall}, then
@code{jit_apply} provides a similar facility.

Even if you don't intend to write a native code generator, you will
probably still need to port @code{jit_apply} to each new architecture.

The @code{libjit} library makes use of gcc's @code{__builtin_apply}
facility to do most of the hard work of function application.
This gcc facility takes three arguments: a pointer to the function
to invoke, a structure containing register arguments, and a size
value that indicates the number of bytes to push onto the stack
for the call.

Unfortunately, the register argument structure is very system dependent.
There is no standard format for it, but it usually looks something
like this:

@table @code
@item stack_args
Pointer to an array of argument values to push onto the stack.

@item struct_ptr
Pointer to the buffer to receive a @code{struct} return value.
The @code{struct_ptr} field is only present if the architecture
passes @code{struct} pointers in a special register.

@item word_reg[0..N]
Values for the word registers.  Platforms that pass values in
registers will populate these fields.  Not present if the architecture
does not use word registers for function calls.

@item float_reg[0..N]
Values for the floating-point registers.  Not present if the architecture
does not use floating-point registers for function calls.
@end table

It is possible to automatically detect the particulars of this structure
by making test function calls and inspecting where the arguments end up
in the structure.  The @code{gen-apply} program in @code{libjit/tools}
takes care of this.  It outputs the @code{jit-apply-rules.h} file,
which tells @code{jit_apply} how to operate.

The @code{gen-apply} program will normally "just work", but it is possible