trick/trick_source/sim_services/JITInputFile/main_page.dox_in

/**

@page LEVEL2 Just-In-Time (JIT) Input File

This capability executes C++ code as an input file.  It is implemented by the
Trick::JITInputFile class.

This class provides a method for injecting code that is not possible to
do through the python input processor or for code that is required to execute
at maximum speed.

@section LEVEL3 Basic Usage

@note When using this capability the simulation is not recompiled.

Here is an example C++ input file to use with the Trick example ball simulation.

@code
// Include S_source.hh to get the sim object definitions and instantiations.
#include "../S_source.hh"

// By default the input processor looks for the run_me function with the following call signature
extern "C" int run_me() {
    // All of the top level sim objects are available by including S_source.hh
    ball.obj.state.input.position[0] = 6.0 ;
    ball.obj.state.input.position[1] = 4.0 ;

    // trick.stop(<time>) in python maps to exec_set_terminate_time in C++
    exec_set_terminate_time(200.0) ;
}
@endcode

There are two ways to use C++ input files.  The first is to use the C++ input file
in place of the normal pyton input file on the command line.  When the input file
is specified on the command line, the input file is compiled and linked into a
shared library during simulation initialization (input_processor phase 50000 job).
The shared library is opened via dlopen and the 'extern "C" int run_me()' is run.

@verbatim
> S_main_Linux_4.4_x86_64.exe RUN_test/input.cpp
@endverbatim

The second method to call C++ input files is to compile and run them within python
input files.

@code
# compile and run a C++ input file.  This call will search for the function "run_me"
trick.jit_compile_and_run("RUN_cpp_input/input.cpp")

# Separately compile and run a C++ input file.
trick.jit_compile("RUN_cpp_input/input.cpp")
trick.jit_run("RUN_cpp_input/input.cpp", "run_event_1")

# compile and run the function run_event_1 from the C++ input file.
trick.jit_compile_and_run("RUN_cpp_input/input.cpp", "run_event_1")
@endcode

@section LEVEL3 Events

Events may be specified through the C++ input file.  Events may be cyclic or tied to a job.
Cyclic events may be one-time events.  All events must be a function call that has the following
call signature "int <event_function>()".

The following examples show the ways to add the different types of events from a C++ input file.

@code
//This event only prints a message
int run_event_1() {
    message_publish(1, "event 1 fired!\n") ;
    return 0 ;
}

int remove_events() {
    jit_remove_event("event_1") ;
    return 0 ;
}

// In this example, we can create independent events that call the same function.  They
// are differentiated by the event name.
extern "C" int run_me() {
    // add read events
    jit_add_read_event( 90.0 , run_event_1 ) ;
    jit_add_read_event( 80.0 , run_event_1 ) ;

    // add cyclic event
    jit_add_cyclic_event( "event_1" , 100.0 , run_event_1 ) ;

    // add another cyclic event
    Trick::JITCyclicEvent * jce = new Trick::JITCyclicEvent("event_2", exec_get_time_tics(),
     (long long)(50.0*exec_get_time_tic_value()), run_event_1 ) ;
    jit_add_cyclic_event( jce ) ;

    // events tied to jobs
    jit_add_event_before( "event_before", run_event_1 , "ball.obj.state_print" ) ;
    jit_add_event_after( "event_after", run_event_1 , "ball.obj.state_print" ) ;

    // another way to tie event to job.
    Trick::JITInstrumentEvent * jie = new Trick::JITInstrumentEvent( "event_before2" , run_event_1 ) ;
    jit_add_event_before( jie , "ball.obj.state_print" ) ;

    // add a read event that removes event 1
    jit_add_read_event( 150.0 , remove_events ) ;
}
@endcode

*/