// vim: ts=4 sw=4 expandtab ft=c

// Copyright (C) 1994-2007, 2009-2011 The University of Melbourne.
// Copyright (C) 2014, 2016, 2018, 2024 The Mercury team.
// This file is distributed under the terms specified in COPYING.LIB.

// mercury_engine.h - definitions for the Mercury runtime engine.
//
// For documentation, see also the comments in mercury_engine.c.

#ifndef MERCURY_ENGINE_H
#define MERCURY_ENGINE_H

// Include mercury_regs.h first so that we don't have any function prototypes
// before the global register declarations.

#include "mercury_regs.h"           // for MR_NUM_REAL_REGS

#include <setjmp.h>

#include "mercury_std.h"            // for `MR_bool'
#include "mercury_types.h"          // for `MR_Code *'
#include "mercury_float.h"          // for `MR_Float'
#include "mercury_goto.h"           // for `MR_define_entry()'
#include "mercury_thread.h"         // for pthread types
#include "mercury_context.h"        // for MR_Context, MR_IF_USE_TRAIL
#include "mercury_conf.h"           // for MR_CONSERVATIVE_GC

////////////////////////////////////////////////////////////////////////////

// Global flags that control the behaviour of the Mercury engine(s).

extern  MR_bool MR_debugflag[];

// These #defines, except MR_MAXFLAG, should not be used anywhere
// except in the immediately following block of #defines, and in the
// array that maps these names to their slots in the source file.

#define MR_PROGFLAG                      0
#define MR_GOTOFLAG                      1
#define MR_CALLFLAG                      2
#define MR_HEAPFLAG                      3
#define MR_DETSTACKFLAG                  4
#define MR_NONDETSTACKFLAG               5
#define MR_FINALFLAG                     6
#define MR_MEMFLAG                       7
#define MR_SREGFLAG                      8
#define MR_TRACEFLAG                     9
#define MR_TABLEFLAG                    10
#define MR_TABLEHASHFLAG                11
#define MR_TABLESTACKFLAG               12
#define MR_UNBUFFLAG                    13
#define MR_AGC_FLAG                     14
#define MR_ORDINARY_REG_FLAG            15
#define MR_ANY_REG_FLAG                 16
#define MR_PRINT_LOCN_FLAG              17
#define MR_LLD_DEBUG_ENABLED_FLAG       18
#define MR_NOT_NEAREST_FLAG             19
#define MR_DEBUG_SLOTS_FLAG             20
#define MR_DEEP_PROF_DEBUG_FILE_FLAG    21
#define MR_STACK_EXTEND_FLAG            22
#define MR_DEEP_PROF_STD_NAME_FLAG      23
#define MR_DETAILFLAG                   24
#define MR_MAXFLAG                      25
// MR_DETAILFLAG should be the last real flag

// The macros control different kinds of low level debugging messages.
// Usually, their values are all false.
//
// MR_progdebug controls whether we want to get several mostly explicitly
// programmed diagnostics.
//
// MR_sregdebug controls whether we want to print the values of the special
// registers (e.g. those that point to the stack) at some diagnostic points.
//
// MR_ordregdebug controls whether we want to print the values of the ordinary
// registers (e.g. r1, r2 etc) at some diagnostic points.
//
// MR_anyregdebug controls whether we want to print the values of the any
// registers, either special or ordinary, at some diagnostic points.
//
// MR_gotodebug controls whether we should generate diagnostics at gotos.
//
// MR_calldebug controls whether we should generate diagnostics when control
// crosses procedure boundaries, i.e. calls, exits, redos and fails.
//
// MR_detstackdebug and MR_nondetstackdebug control whether we should generate
// diagnostics when incrementing and decrementing the pointers to the
// respective stacks.
//
// MR_heapdebug controls whether we should generate diagnostics when we
// allocate memory on the heap.
//
// MR_tabledebug controls whether we should generate diagnostics for tabling
// operations. MR_tablestackdebug control whether these should include the
// contents of stack segments manipulated by minimal model tabling.
// MR_hashdebug controls whether these should include details of hash table
// accesses.
//
// MR_agcdebug controls whether we should generate diagnostics for accurate
// gc operations.
//
// MR_detaildebug controls whether we want more or less detail in some
// diagnostics.
//
// MR_unbufdebug controls whether the runtime will make stdout and stderr
// unbuffered.
//
// MR_memdebug controls whether we want to get diagnostics on the setup of
// memory zones.
//
// MR_finaldebug controls whether we want to get diagnostics showing how
// execution reaches the end of the program.
//
// MR_printlocndebug controls whether we want to get diagnostics showing how
// the runtime system looks up locations recorded in RTTI data structures.
//
// MR_lld_debug_enabled turns on the generation of diagnostic output even when
// they would otherwise be disabled.
//
// MR_not_nearest_flag, if set, tells minimal model tabling to save stack
// segments only to the nearest generator, not to the nearest common ancestor
// of the consumer being suspended and its generator.
//
// MR_debug_slots_flag controls whether dumps of nondet stack frames will
// print the values of the fixed stack slots used by the debugger, in the
// stack frames of procedures compiled with debugging.
//
// MR_deep_prof_debug_file_flag, if set, causes the runtime, whenever it is
// generating a deep profiling .data file, to also generate a human-readable
// debug version of that file.
//
// MR_deep_prof_std_name_flag, if set, causes the runtime, whenever it is
// generating a deep profiling data file, to use the names Deep.data and
// Deep.procrep. The default is to include both the name of the executable
// and the date/time of the program's execution in the filename.
//
// MR_stack_extend_debug controls whether the runtime prints diagnostics
// whenever it extends a stack.

#define MR_progdebug                    MR_debugflag[MR_PROGFLAG]
#define MR_gotodebug                    MR_debugflag[MR_GOTOFLAG]
#define MR_calldebug                    MR_debugflag[MR_CALLFLAG]
#define MR_heapdebug                    MR_debugflag[MR_HEAPFLAG]
#define MR_detstackdebug                MR_debugflag[MR_DETSTACKFLAG]
#define MR_nondetstackdebug             MR_debugflag[MR_NONDETSTACKFLAG]
#define MR_finaldebug                   MR_debugflag[MR_FINALFLAG]
#define MR_memdebug                     MR_debugflag[MR_MEMFLAG]
#define MR_sregdebug                    MR_debugflag[MR_SREGFLAG]
#define MR_tracedebug                   MR_debugflag[MR_TRACEFLAG]
#define MR_tabledebug                   MR_debugflag[MR_TABLEFLAG]
#define MR_hashdebug                    MR_debugflag[MR_TABLEHASHFLAG]
#define MR_tablestackdebug              MR_debugflag[MR_TABLESTACKFLAG]
#define MR_unbufdebug                   MR_debugflag[MR_UNBUFFLAG]
#define MR_agc_debug                    MR_debugflag[MR_AGC_FLAG]
#define MR_ordregdebug                  MR_debugflag[MR_ORDINARY_REG_FLAG]
#define MR_anyregdebug                  MR_debugflag[MR_ANY_REG_FLAG]
#define MR_printlocndebug               MR_debugflag[MR_PRINT_LOCN_FLAG]
#define MR_lld_debug_enabled            MR_debugflag[MR_LLD_DEBUG_ENABLED_FLAG]
#define MR_not_nearest_flag             MR_debugflag[MR_NOT_NEAREST_FLAG]
#define MR_debug_slots_flag             MR_debugflag[MR_DEBUG_SLOTS_FLAG]
#define MR_deep_prof_debug_file_flag    MR_debugflag[                   \
                                            MR_DEEP_PROF_DEBUG_FILE_FLAG]
#define MR_deep_prof_std_name_flag      MR_debugflag[                   \
                                            MR_DEEP_PROF_STD_NAME_FLAG]
#define MR_stack_extend_debug           MR_debugflag[MR_STACK_EXTEND_FLAG]
#define MR_detaildebug                  MR_debugflag[MR_DETAILFLAG]

typedef struct {
    const char      *MR_debug_flag_name;
    int             MR_debug_flag_index;
} MR_Debug_Flag_Info;

extern  MR_Debug_Flag_Info  MR_debug_flag_info[MR_MAXFLAG];

// MR_setjmp and MR_longjmp are wrappers around setjmp and longjmp to ensure
// that
//   call C -> setjmp -> call Mercury -> call C -> longjmp
// works correctly. This is used by the exception handling code for
// the ODBC interface, and probably shouldn't be used for anything else.

typedef struct {
    jmp_buf     *mercury_env;   // used to save MR_ENGINE(MR_eng_jmp_buf)
    jmp_buf     env;            // used by calls to setjmp and longjmp
    MR_Word     *saved_succip;
    MR_Word     *saved_sp;
    MR_Word     *saved_curfr;
    MR_Word     *saved_maxfr;
    MR_IF_USE_TRAIL(MR_TrailEntry   *saved_trail_ptr;)
    MR_IF_USE_TRAIL(MR_Unsigned     saved_ticket_counter;)
    MR_IF_USE_TRAIL(MR_Unsigned     saved_ticket_high_water;)

#if MR_NUM_REAL_REGS > 0
    MR_Word     regs[MR_NUM_REAL_REGS];
#endif // MR_NUM_REAL_REGS > 0
} MR_jmp_buf;

////////////////////////////////////////////////////////////////////////////

// Replacements for setjmp() and longjmp() that work
// across calls to Mercury code.

// MR_setjmp(MR_jmp_buf *env, longjmp_label)
//
// Save MR_ENGINE(MR_eng_jmp_buf), save the Mercury state, call setjmp(env),
// then fall through.
//
// When setjmp returns via a call to longjmp, control will pass to
// longjmp_label.
//
// Notes:
// - The Mercury registers must be valid before the call to MR_setjmp.
// - The general-purpose registers MR_r1, MR_r2... are not restored
//   and must be saved by the caller.
// - In grades without conservative garbage collection, the caller must save
//   and restore hp, sol_hp, heap_zone and solutions_heap_zone.

#define MR_setjmp(setjmp_env, longjmp_label)                                  \
    do {                                                                      \
        (setjmp_env)->mercury_env = MR_ENGINE(MR_eng_jmp_buf);                \
        MR_save_regs_to_mem((setjmp_env)->regs);                              \
        (setjmp_env)->saved_succip = MR_succip;                               \
        (setjmp_env)->saved_sp = MR_sp;                                       \
        (setjmp_env)->saved_curfr = MR_curfr;                                 \
        (setjmp_env)->saved_maxfr = MR_maxfr;                                 \
        MR_IF_USE_TRAIL((setjmp_env)->saved_trail_ptr = MR_trail_ptr);        \
        MR_IF_USE_TRAIL((setjmp_env)->saved_ticket_counter =                  \
            MR_ticket_counter);                                               \
        MR_IF_USE_TRAIL((setjmp_env)->saved_ticket_high_water =               \
            MR_ticket_high_water);                                            \
        if (setjmp((setjmp_env)->env)) {                                      \
            MR_ENGINE(MR_eng_jmp_buf) = (setjmp_env)->mercury_env;            \
            MR_restore_regs_from_mem((setjmp_env)->regs);                     \
            MR_succip_word = (MR_Word) (setjmp_env)->saved_succip;            \
            MR_sp_word = (MR_Word) (setjmp_env)->saved_sp;                    \
            MR_curfr_word = (MR_Word) (setjmp_env)->saved_curfr;              \
            MR_maxfr_word = (MR_Word) (setjmp_env)->saved_maxfr;              \
            MR_IF_USE_TRAIL(MR_trail_ptr = (setjmp_env)->saved_trail_ptr);    \
            MR_IF_USE_TRAIL(MR_ticket_counter =                               \
                (setjmp_env)->saved_ticket_counter);                          \
            MR_IF_USE_TRAIL(MR_ticket_high_water =                            \
                (setjmp_env)->saved_ticket_high_water);                       \
            goto longjmp_label;                                               \
        }                                                                     \
    } while (0)

// MR_longjmp(MR_jmp_buf *env)
//
// Call longjmp(), MR_setjmp() will handle the rest.

#define MR_longjmp(setjmp_env)  longjmp((setjmp_env)->env, 1)

////////////////////////////////////////////////////////////////////////////

// The Mercury engine structure. Normally there is one of these for each
// Posix thread. It contains the following fields.
//
// fake_reg     The fake reg vector for this engine.
//
// hp           The heap pointer for this engine.
//
// sol_hp       The solutions heap pointer for this engine.
//
// global_hp    The global heap pointer for this engine.
//
// MR_eng_parent_sp
//              The stack pointer of the parent contexts' stack frame from
//              which this execution was forked. This is used to implement
//              parallel conjunctions and enable a parallel conjunct to read
//              it's input from it's parent, and to write back it's output.
//
// this_context Points to the "backing store" for the context currently
//              executing on this engine.
//
// context      Stores all the context information for the context currently
//              executing in this engine.
//
//              Conceptually, we could access all information relating to the
//              current context via the MR_eng_this_context field. However,
//              that would require an extra indirection on most accesses,
//              including all accesses to the stack, abstract machine registers
//              etc. That would be too high a cost. We therefore bodily include
//              a context into the engine (in the MR_eng_context) field, and
//              load most of the things pointed to by the MR_eng_this_context
//              field into MR_eng_context. "Most", not "all", because some
//              fields are so rarely accessed that we don't expect the extra
//              cost of context switching to be compensated for by reduced
//              access costs between context switches. These fields are
//              therefore accessed directly via MR_eng_this_context. The big
//              comment in mercury_context.h documents, for each field of the
//              context structure, whether it is accessed by MR_eng_context or
//              via MR_eng_this_context.
//
//              MR_init_thread, invoked by mercury_runtime_init in
//              mercury_wrapper.c, creates the initial MR_eng_this_context
//              for the engine, and then invokes MR_load_context to copy the
//              info from there into the MR_eng_context field.
//
// float_reg
//              The float reg vector for this engine. This exists only if
//              MR_BOXED_FLOAT is defined.
//
// trail_ptr
// ticket_counter
// ticket_high_water
//              These fields correspond to the similarly named global
//              variables declared in mercury_trail.h. They represent
//              the state of the trail for the context that this engine
//              is executing. These fields only exist in parallel trailing
//              grades; in other trailing grades we use the aforementioned
//              globals to store the trail state.
//
// main_context The context of the main computation. The owner_generator field
//              of this context must be NULL.
//
// gen_contexts The contexts of the active generators in this engine.
//              The owner_generator fields of these contexts will point
//              to their generators.
//
// free_contexts
//              Contexts that used to belong to active generators, but which
//              are no longer needed. They are cached here to allow new
//              generators to be created without redoing the work required
//              to allocate a new context.
//
// id           The ID of this engine. It is used to index into some runtime
//              structures. It is also used for threadscope.
//
// type         The type of engine this is.
//
// c_depth
//              The id and c_depth fields are used to ensure that when a thread
//              executing C code calls the Mercury engine associated with that
//              thread, the Mercury code will finish in the same engine and
//              return appropriately. Each time C calls Mercury in a thread,
//              the c_depth is incremented, and the engine id and c_depth
//              values of the current engine are pushed onto the "resume_stack"
//              of the current context. When a context is about to return
//              from Mercury code back into C code, we pop the top entry off the
//              context's resume_stack and check that the context is
//              running on the right engine. If not, we reschedule the context
//              such that it can only be picked up by the correct engine when
//              that engine is available. When the call into the Mercury code
//              finishes, c_depth is decremented.
//
// cpu_clock_ticks_offset
//              The offset to be added to the CPU's TSC to give a time relative
//              to the start of the program.
//
// ts_buffer
//              The buffer object used by threadscope for this engine.
//
// next_spark_id
//              In threadscope grades sparks are given IDs to help us track
//              them. This and MR_eng_id is used to allocate unique IDs.
//
// spark_deque  The sparks generated by contexts executing on this engine.
//
// victim_counter
//              The engine id of this engines' next victim for work stealing.
//
// jmp_buf      The jump buffer used by library/exception.m to return to the
//              runtime system on otherwise unhandled exceptions.
//
// exception    This field is used by library/exception.m to return the
//              identity of the exception that terminates the execution of an
//              engine to the runtime.
//
// heap_zone    The heap zone for this engine.
//
// solutions_heap_zone
//              The solutions heap zone for this engine. We store terms on this
//              heap temporarily while looking for more solutions in an
//              all-solutions predicate.
//
// global_heap_zone
//              The global heap zone for this engine. We store terms on this
//              heap when we want to make them survive resets of hp by
//              backtracking, e.g. for global data structures in the debugger.
//
// heap_zone2   The other heap zone in our two-space collector.
//
// debug_heap_zone
//              A zone used for debugging the accurate gc. Probably not
//              terribly functional.

typedef struct MR_mercury_engine_struct {
    MR_Word             MR_eng_fake_reg[MR_MAX_FAKE_REG];
#ifndef MR_CONSERVATIVE_GC
    MR_Word             *MR_eng_hp;
    MR_Word             *MR_eng_sol_hp;
    MR_Word             *MR_eng_global_hp;
#endif
#ifdef  MR_LL_PARALLEL_CONJ
    MR_Word             *MR_eng_parent_sp;
#endif
    MR_Context          *MR_eng_this_context;
    MR_Context          MR_eng_context;
#ifdef MR_BOXED_FLOAT
    MR_Float            MR_eng_float_reg[MR_MAX_VIRTUAL_F_REG];
#endif
#if defined(MR_THREAD_SAFE) && defined(MR_USE_TRAIL)
    MR_TrailEntry       *MR_eng_trail_ptr;
    MR_Unsigned         MR_eng_ticket_counter;
    MR_Unsigned         MR_eng_ticket_high_water;
#endif
#ifdef  MR_USE_MINIMAL_MODEL_OWN_STACKS
    MR_Context          *MR_eng_main_context;
    MR_Dlist            *MR_eng_gen_contexts;   // elements are MR_Context
    MR_Dlist            *MR_eng_free_contexts;  // elements are MR_Context
#endif
#ifdef  MR_THREAD_SAFE
    MR_EngineId         MR_eng_id;
    MR_EngineType       MR_eng_type;
    MR_Unsigned         MR_eng_c_depth;
  #ifdef MR_THREADSCOPE
    // For each profiling event add this offset to the time so that events on
    // different engines that occur at the same time have the same time in
    // clock ticks.

    MR_int_least64_t                    MR_eng_cpu_clock_ticks_offset;
    struct MR_threadscope_event_buffer  *MR_eng_ts_buffer;
    MR_uint_least32_t                   MR_eng_next_spark_id;
  #endif
  #ifdef MR_LL_PARALLEL_CONJ
    MR_SparkDeque       *MR_eng_spark_deque;
    MR_EngineId         MR_eng_victim_counter;
  #endif
#endif
    jmp_buf             *MR_eng_jmp_buf;
    MR_Word             *MR_eng_exception;
#ifndef MR_CONSERVATIVE_GC
    MR_MemoryZone       *MR_eng_heap_zone;
  #ifdef MR_MIGHT_RECLAIM_HP_ON_FAILURE
    MR_MemoryZone       *MR_eng_solutions_heap_zone;
    MR_MemoryZone       *MR_eng_global_heap_zone;
  #endif
#endif
#ifdef  MR_NATIVE_GC
    MR_MemoryZone       *MR_eng_heap_zone2;
  #ifdef MR_DEBUG_AGC_PRINT_VARS
    MR_MemoryZone       *MR_eng_debug_heap_zone;
  #endif
#endif
} MercuryEngine;

// MR_engine_base refers to the engine in which execution is taking place.
// In the non-thread-safe situation, it is just a global variable.
// In the thread-safe situation, MR_engine_base is either a global
// register (if one is available), a thread-local variable (if compiler
// support is available), or a macro that accesses thread-local storage.
// We provide two macros, MR_ENGINE(x) and MR_CONTEXT(x),
// that can be used in all three kinds of situations to refer to fields
// of the engine structure, and to fields of the engine's current context.

#ifdef  MR_THREAD_SAFE

  #ifdef MR_THREAD_LOCAL_STORAGE
    extern __thread MercuryEngine *MR_thread_engine_base;

    #define MR_set_thread_engine_base(eng)                              \
      do { MR_thread_engine_base = eng; } while (0)
  #else
    extern MercuryThreadKey   MR_engine_base_key;

    #define MR_thread_engine_base                                       \
      ((MercuryEngine *) MR_GETSPECIFIC(MR_engine_base_key))

    #define MR_set_thread_engine_base(eng)                              \
      pthread_setspecific(MR_engine_base_key, eng)
  #endif

  #if MR_NUM_REAL_REGS > 0
    #define MR_ENGINE_BASE_REGISTER
    // MR_engine_base is defined in machdeps/{arch}.h

  #else     // MR_NUM_REAL_REGS == 0

    // MR_maybe_local_thread_engine_base can be redefined to refer to a
    // local copy of MR_thread_engine_base.

    #define MR_maybe_local_thread_engine_base   MR_thread_engine_base
    #define MR_engine_base  MR_maybe_local_thread_engine_base

    #define MR_MAYBE_INIT_LOCAL_THREAD_ENGINE_BASE                      \
        MercuryEngine *MR_local_thread_engine_base = MR_thread_engine_base;

  #endif    // MR_NUM_REAL_REGS == 0

  #define MR_ENGINE(x)      (((MercuryEngine *) MR_engine_base)->x)
  #define MR_cur_engine()   ((MercuryEngine *) MR_engine_base)
  #define MR_get_engine()   ((MercuryEngine *) MR_thread_engine_base)

#else   // !MR_THREAD_SAFE

  extern MercuryEngine      MR_engine_base;
  #define MR_ENGINE(x)      (MR_engine_base.x)
  #define MR_cur_engine()   (&MR_engine_base)
  #define MR_get_engine()   (&MR_engine_base)

#endif  // !MR_THREAD_SAFE

#ifndef MR_MAYBE_INIT_LOCAL_THREAD_ENGINE_BASE
  #define MR_MAYBE_INIT_LOCAL_THREAD_ENGINE_BASE
#endif

#define MR_ENGINE_ID_NONE   ((MR_EngineId) -1)

#define MR_CONTEXT(x)       (MR_ENGINE(MR_eng_context).x)

#ifndef MR_CONSERVATIVE_GC
  #define MR_IF_NOT_CONSERVATIVE_GC(x)  x
#else
  #define MR_IF_NOT_CONSERVATIVE_GC(x)
#endif

#define MR_load_engine_regs(eng)                                              \
    do {                                                                      \
        MR_IF_NOT_CONSERVATIVE_GC(MR_hp_word = (MR_Word) (eng)->MR_eng_hp;)   \
        MR_IF_NOT_CONSERVATIVE_GC(MR_sol_hp = (eng)->MR_eng_sol_hp;)          \
        MR_IF_NOT_CONSERVATIVE_GC(MR_global_hp = (eng)->MR_eng_global_hp;)    \
    } while (0)

#define MR_save_engine_regs(eng)                                              \
    do {                                                                      \
        MR_IF_NOT_CONSERVATIVE_GC((eng)->MR_eng_hp = MR_hp;)                  \
        MR_IF_NOT_CONSERVATIVE_GC((eng)->MR_eng_sol_hp = MR_sol_hp;)          \
        MR_IF_NOT_CONSERVATIVE_GC((eng)->MR_eng_global_hp = MR_global_hp;)    \
    } while (0)

// Functions for creating/destroying a MercuryEngine.

extern  MercuryEngine   *MR_create_engine(void);
extern  void            MR_destroy_engine(MercuryEngine *engine);

// Functions for initializing/finalizing a MercuryEngine.
// These are like create/destroy except that they don't allocate/deallocate
// the MercuryEngine structure.

extern  void            MR_init_engine(MercuryEngine *engine);
extern  void            MR_finalize_engine(MercuryEngine *engine);

// Functions that act on the current Mercury engine.
// See the comments in mercury_engine.c for documentation on MR_call_engine().

extern  MR_Word         *MR_call_engine(MR_Code *entry_point,
                            MR_bool catch_exceptions);
extern  void            MR_terminate_engine(void);
extern  void            MR_dump_prev_locations(void);

////////////////////////////////////////////////////////////////////////////

// Builtin labels that point to some standard code fragments.

MR_declare_entry(MR_do_redo);
MR_declare_entry(MR_do_fail);
MR_declare_entry(MR_do_reset_hp_fail);
MR_declare_entry(MR_do_reset_framevar0_fail);
MR_declare_entry(MR_do_succeed);
MR_declare_entry(MR_do_not_reached);
MR_declare_entry(MR_exception_handler_do_fail);

#endif // not MERCURY_ENGINE_H
