/*
 * jit-context.c - Functions for manipulating JIT contexts.
 *
 * Copyright (C) 2004  Southern Storm Software, Pty Ltd.
 *
 * This file is part of the libjit library.
 *
 * The libjit library is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation, either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * The libjit library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with the libjit library.  If not, see
 * <http://www.gnu.org/licenses/>.
 */

#include "jit-internal.h"

/*@

Everything that is done with @code{libjit} is done relative to a context.
It is possible to have more than one context at a time - each acts as an
independent environment for compiling and managing code.

When you want to compile a function, you create it with
@code{jit_function_create}, and then populate its body with
calls to the value and instruction functions.  See @xref{Values}, and
@ref{Instructions} for more information on how to do this.

@section Using libjit in a multi-threaded environment

The library does not handle the creation, management, and destruction
of threads itself.  It is up to the front-end environment to take
care of that.  But the library is thread-aware, as long as you take
some very simple steps.

In a multi-threaded environment, you must ensure that only one
thread can build functions at any one time.  Otherwise the
JIT's context may become corrupted.  To protect the system,
you should call @code{jit_context_build_start} before
creating the function.  And then call @code{jit_context_build_end}
once the function has been fully compiled.

You can compile multiple functions during the one build process
if you wish, which is the normal case when compiling a class.

It is usually a good idea to suspend the finalization of
garbage-collected objects while function building is in progress.
Otherwise you may get a deadlock when the finalizer thread tries
to call the builder to compile a finalization routine.  Suspension
of finalization is the responsibility of the caller.

@section Context functions
@cindex jit-context.h

The following functions are available to create, manage, and
ultimately destroy JIT contexts:

@*/

/*@
 * @deftypefun jit_context_t jit_context_create (void)
 * Create a new context block for the JIT.  Returns NULL
 * if out of memory.
 * @end deftypefun
@*/
jit_context_t
jit_context_create(void)
{
	jit_context_t context;

	/* Make sure that the JIT is initialized */
	jit_init();

	/* Allocate memory for the context */
	context = jit_cnew(struct _jit_context);
	if(!context)
	{
		return 0;
	}

	/* Initialize the context and return it */
	jit_mutex_create(&context->memory_lock);
	jit_mutex_create(&context->builder_lock);
	context->functions = 0;
	context->last_function = 0;
	context->on_demand_driver = _jit_function_compile_on_demand;
	context->memory_manager = jit_default_memory_manager();
	return context;
}

/*@
 * @deftypefun void jit_context_destroy (jit_context_t @var{context})
 * Destroy a JIT context block and everything that is associated with it.
 * It is very important that no threads within the program are currently
 * running compiled code when this function is called.
 * @end deftypefun
@*/
void
jit_context_destroy(jit_context_t context)
{
	int sym;

	if(!context)
	{
		return;
	}

	for(sym = 0; sym < context->num_registered_symbols; ++sym)
	{
		jit_free(context->registered_symbols[sym]);
	}
	jit_free(context->registered_symbols);

	while(context->functions != 0)
	{
		_jit_function_destroy(context->functions);
	}

	_jit_memory_destroy(context);

	jit_mutex_destroy(&context->memory_lock);
	jit_mutex_destroy(&context->builder_lock);

	jit_free(context);
}

/*@
 * @deftypefun void jit_context_build_start (jit_context_t @var{context})
 * This routine should be called before you start building a function
 * to be JIT'ed.  It acquires a lock on the context to prevent other
 * threads from accessing the build process, since only one thread
 * can be performing build operations at any one time.
 * @end deftypefun
@*/
void
jit_context_build_start(jit_context_t context)
{
	jit_mutex_lock(&context->builder_lock);
}

/*@
 * @deftypefun void jit_context_build_end (jit_context_t @var{context})
 * This routine should be called once you have finished building
 * and compiling a function and are ready to resume normal execution.
 * This routine will release the build lock, allowing other threads
 * that are waiting on the builder to proceed.
 * @end deftypefun
@*/
void
jit_context_build_end(jit_context_t context)
{
	jit_mutex_unlock(&context->builder_lock);
}

/*@
 * @deftypefun void jit_context_set_on_demand_driver (jit_context_t @var{context}, jit_on_demand_driver_func @var{driver})
 * Specify the C function to be called to drive on-demand compilation.
 *
 * When on-demand compilation is requested the default driver provided by
 * @code{libjit} takes the following actions:
 *
 * @enumerate
 * @item
 * The context is locked by calling @code{jit_context_build_start}.
 *
 * @item
 * If the function has already been compiled, @code{libjit} unlocks
 * the context and returns immediately.  This can happen because of race
 * conditions between threads: some other thread may have beaten us
 * to the on-demand compiler.
 *
 * @item
 * The user's on-demand compiler is called.  It is responsible for building
 * the instructions in the function's body.  It should return one of the
 * result codes @code{JIT_RESULT_OK}, @code{JIT_RESULT_COMPILE_ERROR},
 * or @code{JIT_RESULT_OUT_OF_MEMORY}.
 *
 * @item
 * If the user's on-demand function hasn't already done so, @code{libjit}
 * will call @code{jit_function_compile} to compile the function.
 *
 * @item
 * The context is unlocked by calling @code{jit_context_build_end} and
 * @code{libjit} jumps to the newly-compiled entry point.  If an error
 * occurs, a built-in exception of type @code{JIT_RESULT_COMPILE_ERROR}
 * or @code{JIT_RESULT_OUT_OF_MEMORY} will be thrown.
 *
 * @item
 * The entry point of the compiled function is returned from the driver.
 * @end enumerate
 *
 * You may need to provide your own driver if some additional actions
 * are required.
 *
 * @end deftypefun
@*/
void
jit_context_set_on_demand_driver(jit_context_t context, jit_on_demand_driver_func driver)
{
	if (driver)
	{
		context->on_demand_driver = driver;
	}
	else
	{
		context->on_demand_driver = _jit_function_compile_on_demand;
	}
}

/*@
 * @deftypefun void jit_context_set_memory_manager (jit_context_t @var{context}, jit_memory_manager_t @var{manager})
 * Specify the memory manager plug-in.
 * @end deftypefun
@*/
void
jit_context_set_memory_manager(jit_context_t context, jit_memory_manager_t manager)
{
	/* Bail out if there is already an established memory context */
	if (context->memory_context)
	{
		return;
	}

	/* Set the context memory manager */
	if (manager)
	{
		context->memory_manager = manager;
	}
	else
	{
		context->memory_manager = jit_default_memory_manager();
	}
}

/*@
 * @deftypefun int jit_context_set_meta (jit_context_t @var{context}, int @var{type}, void *@var{data}, jit_meta_free_func @var{free_data})
 * Tag a context with some metadata.  Returns zero if out of memory.
 *
 * Metadata may be used to store dependency graphs, branch prediction
 * information, or any other information that is useful to optimizers
 * or code generators.  It can also be used by higher level user code
 * to store information about the context that is specific to the
 * virtual machine or language.
 *
 * If the @var{type} already has some metadata associated with it, then
 * the previous value will be freed.
 * @end deftypefun
@*/
int
jit_context_set_meta(jit_context_t context, int type, void *data, jit_meta_free_func free_data)
{
	return jit_meta_set(&(context->meta), type, data, free_data, 0);
}

/*@
 * @deftypefun int jit_context_set_meta_numeric (jit_context_t @var{context}, int @var{type}, jit_nuint @var{data})
 * Tag a context with numeric metadata.  Returns zero if out of memory.
 * This function is more convenient for accessing the context's
 * special option values:
 *
 * @table @code
 * @vindex JIT_OPTION_CACHE_LIMIT
 * @item JIT_OPTION_CACHE_LIMIT
 * A numeric option that indicates the maximum size in bytes of the function
 * cache.  If set to zero (the default), the function cache is unlimited
 * in size.
 *
 * @vindex JIT_OPTION_CACHE_PAGE_SIZE
 * @item JIT_OPTION_CACHE_PAGE_SIZE
 * A numeric option that indicates the size in bytes of a single page in the
 * function cache.  Memory is allocated for the cache in chunks of
 * this size.  If set to zero, the cache page size is set to an
 * internally-determined default (usually 128k).  The cache page size
 * also determines the maximum size of a single compiled function.
 *
 * @vindex JIT_OPTION_PRE_COMPILE
 * @item JIT_OPTION_PRE_COMPILE
 * A numeric option that indicates that this context is being used
 * for pre-compilation if it is set to a non-zero value.  Code within
 * pre-compiled contexts cannot be executed directly.  Instead, they
 * can be written out to disk in ELF format to be reloaded at
 * some future time.
 *
 * @vindex JIT_OPTION_DONT_FOLD
 * @item JIT_OPTION_DONT_FOLD
 * A numeric option that disables constant folding when it is set to a
 * non-zero value.  This is useful for debugging, as it forces @code{libjit} to
 * always execute constant expressions at run time, instead of at compile time.
 *
 * @vindex JIT_OPTION_POSITION_INDEPENDENT
 * @item JIT_OPTION_POSITION_INDEPENDENT
 * A numeric option that forces generation of position-independent code (PIC)
 * if it is set to a non-zero value. This may be mainly useful for pre-compiled
 * contexts.
 * @end table
 *
 * Metadata type values of 10000 or greater are reserved for internal use.
 * @end deftypefun
@*/
int
jit_context_set_meta_numeric(jit_context_t context, int type, jit_nuint data)
{
	return jit_meta_set(&(context->meta), type, (void *)data, 0, 0);
}

/*@
 * @deftypefun {void *} jit_context_get_meta (jit_context_t @var{context}, int @var{type})
 * Get the metadata associated with a particular tag.  Returns NULL
 * if @var{type} does not have any metadata associated with it.
 * @end deftypefun
@*/
void *
jit_context_get_meta(jit_context_t context, int type)
{
	return jit_meta_get(context->meta, type);
}

/*@
 * @deftypefun jit_nuint jit_context_get_meta_numeric (jit_context_t @var{context}, int @var{type})
 * Get the metadata associated with a particular tag.  Returns zero
 * if @var{type} does not have any metadata associated with it.
 * This version is more convenient for the pre-defined numeric option values.
 * @end deftypefun
@*/
jit_nuint
jit_context_get_meta_numeric(jit_context_t context, int type)
{
	return (jit_nuint)jit_meta_get(context->meta, type);
}

/*@
 * @deftypefun void jit_context_free_meta (jit_context_t @var{context}, int @var{type})
 * Free metadata of a specific type on a context.  Does nothing if
 * the @var{type} does not have any metadata associated with it.
 * @end deftypefun
@*/
void
jit_context_free_meta(jit_context_t context, int type)
{
	jit_meta_free(&(context->meta), type);
}