Falcon::VMachine Class Reference

The Falcon virtual machine. More...

#include <vm.h>

Inheritance diagram for Falcon::VMachine:

List of all members.

Classes

class Pauser

Class automating idle-unidle fragments. More...

class VarDefMod

Structure used to save the vardefs during class link. More...

Public Types

enum {
i_pc_call_request = 0xFFFFFFFF-sizeof(int32)*4, i_pc_redo_request = 0xFFFFFFFF-sizeof(int32)*4, i_pc_call_external_ctor = 0xFFFFFFFF-sizeof(int32)*3, i_pc_call_external_ctor_return = 0xFFFFFFFF-sizeof(int32)*2,
i_pc_call_external = 0xFFFFFFFF-sizeof(int32), i_pc_call_external_return = 0xFFFFFFFF
}

This valuess indicates that the VM is in external execution mode. More...

Public Member Functions

void addLocals (uint32 space)

Adds some local space in the current context.

void allowYield (bool mode)

Change turnover mode.

bool allowYield ()

True if the VM is allowed to execute a context switch.

void appSearchPath (const String &p)

Sets the default application load path (as seen by this vm).

const String & appSearchPath () const

Get the default application load path.

VMBaton & baton ()

Accessor to the VM baton.

const VMBaton & baton () const

Accessor to the VM baton.

void bindItem (const String &name, const Item &value)

Binds a late binding in the current context.

uint32 callbackLoops () const

void callbackLoops (uint32 cl)

bool callCoroFrame (const Item &callable, int32 paramCount)

Executes an executable item in a coroutine.

void callFrame (const Item &callable, int32 paramCount)

Shortcut for to call an item from a VM frame.

void callFrameNow (ext_func_frame_t callbackFunc)

Resets the return handler and prepares to call given external handler.

void callItem (const Item &callable, int32 paramCount, bool asApp=false)

Calls an item.

void callItemAtomic (const Item &callable, int32 paramCount)

Call an item in atomic mode.

void callReturn ()

Return from the last called subroutine.

bool consumeSignal ()

Comsume the currently broadcast signal.

uint32 contextCheckLoops () const

void contextCheckLoops (uint32 cl)

VMContext * coPrepare (int32 paramCount)

Prepare a coroutine context.

PropertyTable * createClassTemplate (LiveModule *lmod, const Map &pt)

Creates the template for a core class.

VMContext * currentContext () const

StackFrame * currentFrame () const

const ItemArray & currentGlobals () const

Returns the current module global variables vector (const version).

ItemArray & currentGlobals ()

Returns the current module global variables vector.

LiveModule * currentLiveModule () const

Returns the module in which the execution is currently taking place.

const Module * currentModule () const

Returns the module in which the execution is currently taking place.

const Symbol * currentSymbol () const

void decref ()

Decrements the reference count for this virtual machine.

uint32 elapsedLoops () const

Return the loops that this VM has performed.

void electContext ()

Elects a new context ready for execution.

void execFrame ()

Executes currently prepared frame.

returnCode expandString (const String &src, String &target)

Performs a string expansion.

void expandTRAV (uint32 count, Iterator &iter)

Expand a number of variables from the current value of an iterator.

bool exportAllSymbols (LiveModule *mod)

Exports all symbols in a module.

bool exportSymbol (const Symbol *sym, LiveModule *mod)

Exports a single symbol.

void fillErrorContext (Error *err, bool filltb=true)

Fills an error with current VM execution context and traceback.

void fillErrorTraceback (Error &error)

Fills an error traceback with the current VM traceback.

void finalize ()

Terminates this VM activity.

Item * findGlobalItem (const String &name) const

Returns a live global given the name of its symbol.

const SymModule * findGlobalSymbol (const String &str) const

Item * findLocalSymbolItem (const String &symName) const

Returns the value of a local variable.

bool findLocalVariable (const String &name, Item &data) const

Returns the value of a local variable.

LiveModule * findModule (const String &name)

Find a linked module with a given name.

Item * findWKI (const String &name) const

Returns a well known item.

bool functionalEval (const Item &itm, uint32 pcount=0, bool retArray=true)

Evaluate the item in a functional context.

uint32 gcCheckLoops () const

void gcCheckLoops (uint32 cl)

void gcEnable (bool mode)

Enable the Garbage Collector requests on this VM.

uint32 generation () const

Return current generation.

Item * getBinding (const String &bind) const

Return the value associated with a binding symbol.

bool getCaller (const Symbol *&sym, const Module *&module)

Get the caller of the current symbol.

bool getCallerItem (Item &caller, uint32 level=0)

Get the item that called the current symbol.

const ContextList * getCtxList () const

CoreClass * getMetaClass (int itemID)

Item * getSafeBinding (const String &bind)

Return the value associated with a binding symbol, or creates one if not found.

Service * getService (const String &name)

Queries the VM for a published service.

const ContextList * getSleepingList () const

CoreSlot * getSlot (const String &slotName, bool create=true)

Gets a slot for a given message.

void hasProcessStreams (bool b)

Indicastes if this VM has been given standard streams control or not.

bool hasProcessStreams () const

void idle ()

Declares an IDLE section.

void incref ()

Increments the reference count for this VMachine.

void init ()

Initialize the virutal machine.

void initializeInstance (const Symbol *sym, LiveModule *livemod)

Constructs an instance calling its _init method if necessary.

void interrupt ()

Interrupts pending I/O on this machine from a separate thread.

bool interrupted (bool raise=false, bool reset=false, bool dontCheck=false)

Returns true if the VM has been interrupted.

bool isGcEnabled () const

bool isParamByRef (uint32 itemId) const

Returns true if the nth element of the current function has been passed by reference.

void itemToString (String &target, const Item *itm)

void itemToString (String &target, const Item *itm, const String &format)

Converts an item into a string.

void jump (uint32 pos)

Change the position of the next executed instruction.

Item & latch ()

Latch item.

const Item & latch () const

Latch item.

Item & latcher ()

Latcher item.

const Item & latcher () const

Latcher item.

void launch (const String &startSym, uint32 paramCount=0)

Launches a routine.

void launch ()

Launches the "__main__" symbol.

bool launchAtLink () const

Returns the launch-at-link mode.

void launchAtLink (bool mode)

Changes the status of launch-at-link mode.

uint32 limitLoops () const

void limitLoops (uint32 l)

bool limitLoopsHit () const

LiveModule * link (Module *module, bool isMainModule=true, bool bPrivate=false)

Links a single module.

LiveModule * link (Runtime *rt)

Links a set of modules stored in a runtime.

CoreClass * linkClass (LiveModule *lmod, const Symbol *clsym)

Creates a new class live item.

bool linkClassSymbol (const Symbol *sym, LiveModule *livemod)

Links a class symbol.

bool linkCompleteSymbol (Symbol *sym, const String &moduleName)

Links a symbol eventually performing class and instances initializations.

bool linkCompleteSymbol (const Symbol *sym, LiveModule *livemod)

Links a symbol eventually performing class and instances initializations.

bool linkInstanceSymbol (const Symbol *sym, LiveModule *livemod)

Links a class instance.

bool linkSymbol (const Symbol *sym, LiveModule *lmod)

Links a single symbol on an already existing live module.

virtual bool linkSymbolDynamic (const String &name, SymModule &symdata)

Try to link a dynamic symbol.

const LiveModuleMap & liveModules () const

Return the map of live modules ordered by name (const version).

LiveModuleMap & liveModules ()

Return the map of live modules ordered by name.

Item * local (uint32 itemId)

Returns the nth local item.

const Item * local (uint32 itemId) const

Returns the nth local item.

LiveModule * mainModule () const

Returns the main module, if it exists.

void markSlots (uint32 mark)

Used by the garbage collector to accunt for items stored as slot callbacks.

const Item & moduleItem (uint32 pos) const

Returns a reference to the nth item in the current module global variables vector (const version).

Item & moduleItem (uint32 pos)

Returns a reference to the nth item in the current module global variables vector.

const String & moduleString (uint32 stringId) const

Return current module string at given ID.

virtual void onIdleTime (numeric seconds)

Call back on sleep requests.

byte operandType (byte opNum) const

Item * param (uint32 itemId)

Returns the nth paramter passed to the VM.

const Item * param (uint32 itemId) const

Returns the nth paramter passed to the VM.

int32 paramCount () const

Returns the parameter count for the current function.

void performGC (bool bWaitForCollection=false)

Force a GC collection loop on the virtual machine.

virtual void periodicCallback ()

Periodic callback.

void popTry (bool moveTo)

Pop a try position, eventually changing the frame to the handler.

void postMessage (VMMessage *vm)

Send a message to the VMachine.

void prepareFrame (CoreArray *ca, uint32 paramCount)

Prepare a frame for an array call.

void prepareFrame (CoreFunc *cf, uint32 paramCount)

Prepare a frame for a function call.

uint32 programCounter () const

void publishService (Service *svr)

Publish a service.

void pushParameter (const Item &item)

Pushes a parameter for the vm callItem and callFrame functions.

void pushTry (uint32 landingPC)

Push current try position.

void recallFrame ()

Prepare the VM to recall current return frame.

void referenceItem (Item &target, Item &source)

Creates a reference to an item.

Item & regA ()

const Item & regA () const

Item & regB ()

const Item & regB () const

Item & regBind ()

const Item & regBind () const

Item & regBindP ()

const Item & regBindP () const

void removeSlot (const String &slotName)

Removes and dereference a message slot in the VM.

void requestConstruct ()

Request a constructor call after a call frame.

void reset ()

Reset machine for a clean execution.

void resetCounters ()

void retnil ()

ext_func_frame_t returnHandler ()

Returns currently installed return handler, or zero if none.

ext_func_frame_t returnHandler () const

void returnHandler (ext_func_frame_t callbackFunc)

Installs a post-processing return frame handler.

void retval (const String &cs)

void retval (CoreClass *cc)

void retval (CoreObject *co)

void retval (CoreDict *cd)

void retval (MemBuf *mb)

void retval (CoreArray *ca)

void retval (CoreString *cs)

Returns a garbageable string.

void retval (String *cs)

Returns a non garbageable string.

void retval (const Item &val)

void retval (numeric val)

void retval (int64 val)

void retval (int32 val)

void retval (bool val)

void rotateContext ()

void run ()

Virtual machine main loop.

Item & self ()

const Item & self () const

bool setBinding (const String &bind, const Item &value)

Set a binding value.

void setBindingContext (CoreDict *ctx)

Set current binding context.

void setFinalizeCallback (void(*finfunc)(VMachine *vm))

Finalization callback function (used by MT).

void setMetaClass (int itemID, CoreClass *metaClass)

void setupScript (int argc, char **argv)

Setup the main script standard parameters and variables.

bool singleStep () const

void singleStep (bool ss)

const ItemArray & stack () const

Returns the current stack as a reference (const version).

ItemArray & stack ()

Returns the current stack as a reference.

uint32 & stackBase ()

const uint32 & stackBase () const

const Item & stackItem (uint32 pos) const

Returns a reference to the nth item in the current stack (const version).

Item & stackItem (uint32 pos)

Returns a reference to the nth item in the current stack.

void stdErr (Stream *nstream)

Set stdandard error stream.

Stream * stdErr () const

Gets the standard input stream associated with this VM.

void stdIn (Stream *nstream)

Set stdandard input stream.

Stream * stdIn () const

Gets the standard input stream associated with this VM.

void stdOut (Stream *nstream)

Set stdandard output stream.

Stream * stdOut () const

Gets the standard input stream associated with this VM.

void step ()

Performs a single VM step and return.

Sys::SystemData & systemData ()

Get System Specific data (non const).

const Sys::SystemData & systemData () const

Get System Specific data.

void terminateCurrentContext ()

const uint32 & tryFrame () const

Returns the current try frame as a reference (const version).

uint32 & tryFrame ()

Returns the current try frame as a reference.

void unbindItem (const String &name, Item &tgt) const

Unbinds a late binding on the given target.

void unidle ()

Declares the end of an idle code section.

bool unlink (const Module *module)

Unlinks a module.

bool unlink (const Runtime *rt)

Unlinks all the modules in the runtime.

void * userData () const

Get the user data associated with this VM.

void userData (void *ud)

Set user data.

VMachine ()

Creates the virtual machine.

VMachine (bool initItems)

Initialize VM from subclasses.

void yield (numeric seconds)

Make this context to sleep and elect a new one.

Static Public Member Functions

static VMachine * getCurrent ()

Returns the currently running VM.

Protected Types

enum { i_noTryFrame = 0xFFFFFFFF }

This value indicate that there isn't any active try handler in the stack. More...

Protected Member Functions

bool completeModLink (LiveModule *lmod)

void createFrame (uint32 paramCount, ext_func_frame_t frameEndFunc=0)

Creates a new stack frame in the current context.

int32 getNextNTD32 ()

Returns the next NTD32 parameter, advancing the pointer to the next instruction.

int64 getNextNTD64 ()

Returns the next NTD64 parameter, advancing the pointer to the next instruction.

Item * getNextTravVar ()

Gets the next item in a trav loop.

Item * getOpcodeParam (register uint32 bc_pos)

Gets the nth parameter of an opcode.

void handleRaisedError (Error *err)

Decides what to do with an error incoming in the main loop.

void handleRaisedItem (Item &value)

Perform an item raise.

void internal_construct ()

bool linkDefinedSymbol (const Symbol *sym, LiveModule *lmod)

bool linkSubClass (LiveModule *mod, const Symbol *clssym, Map &props, ObjectFactory *factory)

Service recursive function called by LinkClass to create a class.

bool linkUndefinedSymbol (const Symbol *sym, LiveModule *lmod)

Item * parseSquareAccessor (const Item &accessed, String &accessor) const

void periodicChecks ()

Performs periodic checks on the virtual machine.

LiveModule * prelink (Module *mod, bool bIsMain, bool bPrivate)

void processMessage (VMMessage *msg)

Processes an incoming message.

void putAtSleep (VMContext *ctx)

Puts the given context at sleep.

void raiseHardError (int code, const String &expl, int32 line)

void reschedule (VMContext *ctx)

Resort this context changing its position in the sleep list.

bool seekInRange (int64 num, byte *base, uint16 size, uint32 &landing) const

Utility for switch opcode.

bool seekInteger (int64 num, byte *base, uint16 size, uint32 &landing) const

Utility for switch opcode.

bool seekItem (const Item *item, byte *base, uint16 size, uint32 &landing)

Utility for switch opcode.

bool seekItemClass (const Item *obj, byte *base, uint16 size, uint32 &landing) const

Utility for select opcode.

bool seekString (const String *str, byte *base, uint16 size, uint32 &landing) const

Utility for switch opcode.

void setCurrent () const

Sets the currently running VM.

virtual ~VMachine ()

Destroys the virtual machine.

Protected Attributes

bool m_allowYield

Wether or not to allow a VM hostile takeover of the current context.

String m_appSearchPath

filtered load path

VMBaton m_baton

Main synchronization baton.

bool m_bGcEnabled

If true, the VM allows to be blocked periodically by the GC in case of need.

bool m_bhasStandardStreams

bool m_bPirorityGC

Event set by the VM to ask for priority GC.

bool m_bSingleStep

True for single stepping.

bool m_bWaitForCollect

True when we want to wait for collection before being notified in priority scans.

ContextList m_contexts

Ready to run contexts.

VMContext * m_currentContext

Context currently being executed.

Event m_eGCPerformed

Event set by the GC to confirm the forced GC loop is over.

uint32 m_generation

Generation at which the garbage data in this VM is marked.

SymModuleMap m_globalSyms

Map of global symbols (and the item they are connected to).

VMachine * m_idleNext

VMachine * m_idlePrev

Item m_imm [4]

Space for immediate operands.

bool m_launchAtLink

Execute at link time?

LiveModuleMap m_liveModules

Map of live modules.

GarbageLock * m_lockRoot

Locked and unreclaimable items are stored in this ring.

uint32 m_loopsCallback

Timeout for Callbacks.

uint32 m_loopsContext

Timeout for Context checks.

uint32 m_loopsGC

Timeout for GC collection.

LiveModule * m_mainModule

Main module.

CoreClass ** m_metaClasses

VMMessage * m_msg_head

VMMessage * m_msg_tail

Mutex m_mtx

Mutex m_mtx_lockitem

Mutex for locked items ring.

Mutex m_mtx_mesasges

VMachine * m_nextVM

void(* m_onFinalize )(VMachine *vm)

Finalization hook for MT system.

uint32 m_opCount

Number of opcodes that the current coroutine has performed.

tOpcodeHandler * m_opHandlers

Opcode handler function calls.

uint32 m_opLimit

Maximum operations that can be performed.

uint32 m_opNextCallback

uint32 m_opNextCheck

Smaller check in op loops.

uint32 m_opNextContext

uint32 m_opNextGC

VMachine * m_prevVM

volatile int m_refcount

Reference count.

Map m_services

Subscribed services map.

ContextList m_sleepingContexts

Contexts willing to sleep for a while.

Mutex m_slot_mtx

Mutex guarding the slot structure.

Map m_slots

Stream * m_stdErr

Stream * m_stdIn

Stream * m_stdOut

Sys::SystemData m_systemData

System specific data.

void * m_userData

User available pointer.

SymModuleMap m_wellKnownSyms

Map of well knwon symbols (and the item they are connected to).

Friends

class MemPool

void opcodeHandler_ADD (register VMachine *vm)

void opcodeHandler_ADDS (register VMachine *vm)

void opcodeHandler_AND (register VMachine *vm)

void opcodeHandler_ANDS (register VMachine *vm)

void opcodeHandler_BAND (register VMachine *vm)

void opcodeHandler_BNOT (register VMachine *vm)

void opcodeHandler_BOOL (register VMachine *vm)

void opcodeHandler_BOR (register VMachine *vm)

void opcodeHandler_BXOR (register VMachine *vm)

void opcodeHandler_CALL (register VMachine *vm)

void opcodeHandler_CLOS (register VMachine *vm)

void opcodeHandler_DEC (register VMachine *vm)

void opcodeHandler_DECP (register VMachine *vm)

void opcodeHandler_DIV (register VMachine *vm)

void opcodeHandler_DIVS (register VMachine *vm)

void opcodeHandler_END (register VMachine *vm)

End opcode handler.

void opcodeHandler_EQ (register VMachine *vm)

void opcodeHandler_EVAL (register VMachine *vm)

void opcodeHandler_FORB (register VMachine *vm)

void opcodeHandler_FORK (register VMachine *vm)

void opcodeHandler_GE (register VMachine *vm)

void opcodeHandler_GENA (register VMachine *vm)

void opcodeHandler_GEND (register VMachine *vm)

void opcodeHandler_GENR (register VMachine *vm)

void opcodeHandler_GEOR (register VMachine *vm)

void opcodeHandler_GT (register VMachine *vm)

void opcodeHandler_IFF (register VMachine *vm)

void opcodeHandler_IFT (register VMachine *vm)

void opcodeHandler_IN (register VMachine *vm)

void opcodeHandler_INC (register VMachine *vm)

void opcodeHandler_INCP (register VMachine *vm)

void opcodeHandler_INDI (register VMachine *vm)

void opcodeHandler_INST (register VMachine *vm)

void opcodeHandler_IPOP (register VMachine *vm)

void opcodeHandler_JMP (register VMachine *vm)

void opcodeHandler_JTRY (register VMachine *vm)

void opcodeHandler_LD (register VMachine *vm)

void opcodeHandler_LDAS (register VMachine *vm)

void opcodeHandler_LDP (register VMachine *vm)

void opcodeHandler_LDPT (register VMachine *vm)

void opcodeHandler_LDRF (register VMachine *vm)

void opcodeHandler_LDV (register VMachine *vm)

void opcodeHandler_LDVT (register VMachine *vm)

void opcodeHandler_LE (register VMachine *vm)

void opcodeHandler_LNIL (register VMachine *vm)

void opcodeHandler_LSB (register VMachine *vm)

void opcodeHandler_LSTA (register VMachine *vm)

void opcodeHandler_LT (register VMachine *vm)

void opcodeHandler_LVAL (register VMachine *vm)

void opcodeHandler_MOD (register VMachine *vm)

void opcodeHandler_MODS (register VMachine *vm)

void opcodeHandler_MUL (register VMachine *vm)

void opcodeHandler_MULS (register VMachine *vm)

void opcodeHandler_NEG (register VMachine *vm)

void opcodeHandler_NEQ (register VMachine *vm)

void opcodeHandler_NOIN (register VMachine *vm)

void opcodeHandler_NOP (register VMachine *vm)

void opcodeHandler_NOT (register VMachine *vm)

void opcodeHandler_NOTS (register VMachine *vm)

void opcodeHandler_ONCE (register VMachine *vm)

void opcodeHandler_OOB (register VMachine *vm)

void opcodeHandler_OR (register VMachine *vm)

void opcodeHandler_ORS (register VMachine *vm)

void opcodeHandler_PASS (register VMachine *vm)

void opcodeHandler_PEEK (register VMachine *vm)

void opcodeHandler_POP (register VMachine *vm)

void opcodeHandler_POW (register VMachine *vm)

void opcodeHandler_POWS (register VMachine *vm)

void opcodeHandler_PROV (register VMachine *vm)

void opcodeHandler_PSHL (register VMachine *vm)

void opcodeHandler_PSHN (register VMachine *vm)

void opcodeHandler_PSHR (register VMachine *vm)

void opcodeHandler_PSIN (register VMachine *vm)

void opcodeHandler_PTRY (register VMachine *vm)

void opcodeHandler_PUSH (register VMachine *vm)

void opcodeHandler_RET (register VMachine *vm)

void opcodeHandler_RETA (register VMachine *vm)

void opcodeHandler_RETV (register VMachine *vm)

void opcodeHandler_RIS (register VMachine *vm)

void opcodeHandler_SELE (register VMachine *vm)

void opcodeHandler_SHL (register VMachine *vm)

void opcodeHandler_SHLS (register VMachine *vm)

void opcodeHandler_SHR (register VMachine *vm)

void opcodeHandler_SHRS (register VMachine *vm)

void opcodeHandler_SSTA (register VMachine *vm)

void opcodeHandler_STEX (register VMachine *vm)

void opcodeHandler_STO (register VMachine *vm)

void opcodeHandler_STP (register VMachine *vm)

void opcodeHandler_STPR (register VMachine *vm)

void opcodeHandler_STPS (register VMachine *vm)

void opcodeHandler_STV (register VMachine *vm)

void opcodeHandler_STVR (register VMachine *vm)

void opcodeHandler_STVS (register VMachine *vm)

void opcodeHandler_SUB (register VMachine *vm)

void opcodeHandler_SUBS (register VMachine *vm)

void opcodeHandler_SVAL (register VMachine *vm)

void opcodeHandler_SWCH (register VMachine *vm)

void opcodeHandler_TRAC (register VMachine *vm)

void opcodeHandler_TRAL (register VMachine *vm)

void opcodeHandler_TRAN (register VMachine *vm)

void opcodeHandler_TRAV (register VMachine *vm)

void opcodeHandler_TRDN (register VMachine *vm)

void opcodeHandler_TRY (register VMachine *vm)

void opcodeHandler_WRT (register VMachine *vm)

void opcodeHandler_XORS (register VMachine *vm)

void opcodeHandler_XPOP (register VMachine *vm)

class VMContext

class VMSemaphore

Detailed Description

The Falcon virtual machine.

Virtual machine is in charge to execute Falcon bytecode.

The virtual machine execution model is quite flexible, and allow infinite execution, step-by-step execution, limited runs and interrupts (event rising and debug requests) from external code while running.

To run, the Virtual Machine needs to be properly setup. However, this "setup steps" are thought as customization steps so that the VM user is able to configure it on its needs, and they are both simple and effective.

Minimal configuration needed requires to add a Runtime object, which holds the lists of all non-main modules. It is then possible to execute a routine exported by any of the modules in the runtime, or to provide a "running module", or "main module" with the setup() method. Once the startup symbol, or running module (or both) are set, the it is possible to call run().

Note:: It is possible that this interface will be simplified in the future so that only one method is used to set up the runtime and the start symbol or main module.
This class implements the error handler interface because it may act as an error handler for the embedding components: compiler, assembler, module loader and runtime may all be embedded in a VM that may act as a referee for the script to be i.e. evaluating correctly a piece of falcon source code.

Member Enumeration Documentation

anonymous enum

This valuess indicates that the VM is in external execution mode.

With this value in m_pc, the VM will execute the symbol found in m_symbol.

Enumerator:

i_pc_call_request
i_pc_redo_request
i_pc_call_external_ctor
i_pc_call_external_ctor_return
i_pc_call_external
i_pc_call_external_return

anonymous enum [protected]

This value indicate that there isn't any active try handler in the stack.

Enumerator:

i_noTryFrame

enum Falcon::VMachine::returnCode

Types of return values.

When a function may return more than simply syccess or failure, this code specifies what went wrong in a VM function.

Enumerator:

return_ok
return_error_string
return_error_parse
return_error_internal
return_error_parse_fmt

enum Falcon::VMachine::t_linkMode

Enumerator:

lm_complete
lm_prelink
lm_postlink

Constructor & Destructor Documentation

virtual Falcon::VMachine::~VMachine ( ) [protected, virtual]

Destroys the virtual machine.

Protected as it can't be called directly.

Falcon::VMachine::VMachine ( bool initItems )

Initialize VM from subclasses.

Subclasses willing to provide their own initialization routine, or code wishing to configure the machine, may use this constructor to prevent the call of the init() routine of this class, which fills some configurable component of the machine.

Parameters:

initItems

false to prevent creation of base items

See also:: init()

Falcon::VMachine::VMachine ( )

Creates the virtual machine.

The default constructor calss the virtual method init(). Subclasses may overload it to setup personalized VMs.

See also:: init().

Member Function Documentation

void Falcon::VMachine::addLocals ( uint32 space ) [inline]

Adds some local space in the current context.

Parameters:

amount

how many local variables must be created

References Falcon::VMContext::addLocals().

void Falcon::VMachine::allowYield ( bool mode ) [inline]

Change turnover mode.

bool Falcon::VMachine::allowYield ( ) [inline]

True if the VM is allowed to execute a context switch.

void Falcon::VMachine::appSearchPath ( const String & p ) [inline]

Sets the default application load path (as seen by this vm).

const String& Falcon::VMachine::appSearchPath ( ) const [inline]

Get the default application load path.

VMBaton& Falcon::VMachine::baton ( ) [inline]

Accessor to the VM baton.

Used to serialize concurrent access to this VM.

const VMBaton& Falcon::VMachine::baton ( ) const [inline]

Accessor to the VM baton.

Used to serialize concurrent access to this VM.

void Falcon::VMachine::bindItem	(	const String &	name,
		const Item &	value
	)

Binds a late binding in the current context.

As late bindings are known by name, only the name is necessary for the binding to complete.

Parameters:

	name	the symbolic name of the binding.
	value	the value to be associated with the late binding.

uint32 Falcon::VMachine::callbackLoops ( ) const [inline]

void Falcon::VMachine::callbackLoops ( uint32 cl ) [inline]

bool Falcon::VMachine::callCoroFrame	(	const Item &	callable,
		int32	paramCount
	)

Executes an executable item in a coroutine.

Parameters:

	callable	The callable routine.
	paramCount	Number of parameters to be passed in the coroutine stack.

void Falcon::VMachine::callFrame	(	const Item &	callable,
		int32	paramCount
	)			`[inline]`

Shortcut for to call an item from a VM frame.

Extension functions and VM/core functions meant to be called from the run() loop should use this function instead the callItem.

The function prepares the VM to execute the desired item at the next run loop, as soon as the calling function returns.

The caller should return immediately, or after a short cleanup, in case the call is succesful (and the function returns true).

If the function needs to continue or do some post-processing after calling the callable item, it must install a return frame handler using returnHandler()

References Falcon::Item::readyFrame().

void Falcon::VMachine::callFrameNow ( ext_func_frame_t callbackFunc )

Resets the return handler and prepares to call given external handler.

This function prepares the VM to execute a return handler immediately after the calling function returns.

The net effect is that, when called from inside an extension function, the given callback will be called by the VM as the very next operation, after checks on events, timings and context switches.

The difference with callFrame is that the stack is unaffected, and the called function will have the same call frame as the caller.

The difference with returnHandler is that the VM is instructed to execute the retun procedure (that will call the given call back function) immediately, while returnHandler just sets an handler for a future time when the readied call frame will be unrolled.

This function can be safely called from inside the same callback function, so to create loops in which each call goes through VM checks for operation counts and events.

The callbackFunc should behave as specified for returnHandler(), returning true if creating another frame with callFrame() or calling another return handler (or even itself) using callFrameNow().

Note:: recallFrame() is a (more) efficient shortcut for using callFrameNow on the same calling function.

See also:: returnHandler()

Parameters:

callbackFunc

the function to be called ASAP.

void Falcon::VMachine::callItem	(	const Item &	callable,
		int32	paramCount,
		bool	asApp = `false`
	)			`[inline]`

Calls an item.

The item may contain any valid callable object:

An external (C/C++) function.
A falcon function.
A method
A class

External functions are immediately called, the flow of the VM being interrupted.

Falcon function and method calls prepare this vm to execute the first instruction of the item, pushing a stack frame that allows RET and similar pcodes to return to the VM instruction after the one that was currently being executed. Control may or may not return immediately to the caller; if e_callNormal, e_callInst or e_callPassIn modes are used, the function returns only after the called item returns, else the function returns immediately and the vm is readied to continue execution from the new position.

Class calls actually searches for the class constructor, and call that one. If the called class has no constructor, the function returns true but actually does nothing.

Before calling this function, enough parameters must be pushed in the stack using pushParameter() method.

The paramCount parameter must be smaller or equal to the size of the stack, or an unblockable error will be raised.

Parameters:

	callable	the item to be called.
	paramCount	the number of elements in the stack to be considered parameters.
	asApp	Consider this as falcon application entry point. If true, the VM will throw a VMQuitEvent autonomously when finished.
	mode	the item call mode.

void Falcon::VMachine::callItemAtomic	(	const Item &	callable,
		int32	paramCount
	)

Call an item in atomic mode.

This method is meant to call the vm run loop from inside another vm run loop. When this is necessary, the inner call must end as soon as possible. The VM becomes unprehemptible; contexts are never switched, operation count limits (except for hard limits) are not accounted and any explicit try to ask for the VM to suspend, wait, yield or sleep raises an unblockable error.

Things to be called in atomic mode are i.e. small VM operations overload methods, as the toString or the compare. All the rest should be performed using the callFrame mechanism.

Exceptions:

CodeError

if the item is not callable.

void Falcon::VMachine::callReturn ( )

Return from the last called subroutine.

Usually used internally by the opcodes of the VM.

bool Falcon::VMachine::completeModLink ( LiveModule * lmod ) [protected]

bool Falcon::VMachine::consumeSignal ( )

Comsume the currently broadcast signal.

This blocks the processing of signals to further listener of the currently broadcasting slot.

Returns:: true if the signal is consumed, false if there was no signal to consume.

uint32 Falcon::VMachine::contextCheckLoops ( ) const [inline]

void Falcon::VMachine::contextCheckLoops ( uint32 cl ) [inline]

VMContext* Falcon::VMachine::coPrepare ( int32 paramCount )

Prepare a coroutine context.

The context is immediately swapped, so any operation performed by the caller is done on the new context. This allow to call an item right after coroutine creation.

Parameters:

paramCount

Number of parameters to be passed in the coroutine stack.

PropertyTable* Falcon::VMachine::createClassTemplate	(	LiveModule *	lmod,
		const Map &	pt
	)

Creates the template for a core class.

Parameters:

	lmod	the module id for which this class is being created.
	pt	a ClassDef wise property table containing properties definition.

Returns:: a newly created property table ready to be added to a core class.

void Falcon::VMachine::createFrame	(	uint32	paramCount,
		ext_func_frame_t	frameEndFunc = `0`
	)			`[inline, protected]`

Creates a new stack frame in the current context.

Parameters:

	paramCount	number of parameters in the stack
	frameEndFunc	Callback function to be executed at frame end

References Falcon::VMContext::createFrame().

VMContext* Falcon::VMachine::currentContext ( ) const [inline]

StackFrame* Falcon::VMachine::currentFrame ( ) const [inline]

References Falcon::VMContext::currentFrame().

const ItemArray& Falcon::VMachine::currentGlobals ( ) const [inline]

Returns the current module global variables vector (const version).

References Falcon::VMContext::globals().

ItemArray& Falcon::VMachine::currentGlobals ( ) [inline]

Returns the current module global variables vector.

References Falcon::VMContext::globals().

LiveModule* Falcon::VMachine::currentLiveModule ( ) const [inline]

Returns the module in which the execution is currently taking place.

References Falcon::VMContext::lmodule().

const Module* Falcon::VMachine::currentModule ( ) const [inline]

Returns the module in which the execution is currently taking place.

References Falcon::VMContext::lmodule(), and Falcon::LiveModule::module().

const Symbol* Falcon::VMachine::currentSymbol ( ) const [inline]

References Falcon::VMContext::symbol().

void Falcon::VMachine::decref ( )

Decrements the reference count for this virtual machine.

If the count hits zero, the virtual machine is immediately destroyed.

uint32 Falcon::VMachine::elapsedLoops ( ) const [inline]

Return the loops that this VM has performed.

There is no guarantee that the loops performed by the virtual machine hadn't overflown the uint32 size, nuless there is a physical loop limit set with loopLimit(). However, this counter can be useful to check different algorithm performances.

void Falcon::VMachine::electContext ( )

Elects a new context ready for execution.

This method should be called by embedding applications that have performed a sleep operations right after the elapsed sleep time. The VM will elect the most suitable context for execution.

On output, the VM will be ready to run (call the run() function); if no context is willing to run yet, there this method will set the eventSleep (hadSleepRequest() will return true), and the sleep request time will be propery set.

void Falcon::VMachine::execFrame ( ) [inline]

Executes currently prepared frame.

References Falcon::VMContext::pc(), and Falcon::VMContext::pc_next().

returnCode Falcon::VMachine::expandString	(	const String &	src,
		String &	target
	)

Performs a string expansion.

Returns:: a returnCode enumeration explaining possible errors in string expansion

void Falcon::VMachine::expandTRAV	(	uint32	count,
		Iterator &	iter
	)

Expand a number of variables from the current value of an iterator.

Uses the current VM pc_next position to decode count variables stored in NOP opcodes, storing the current value of the iterator into them.

bool Falcon::VMachine::exportAllSymbols ( LiveModule * mod )

Exports all symbols in a module.

To be called when changing the module publicity policy.

bool Falcon::VMachine::exportSymbol	(	const Symbol *	sym,
		LiveModule *	mod
	)

Exports a single symbol.

This publishes a symbol on the global symbol map, and/or eventually to the WKS map.

The function checks for the symbol to be exported and/or Well Known before actually performing the final export.

void Falcon::VMachine::fillErrorContext	(	Error *	err,
		bool	filltb = `true`
	)

Fills an error with current VM execution context and traceback.

void Falcon::VMachine::fillErrorTraceback ( Error & error )

Fills an error traceback with the current VM traceback.

void Falcon::VMachine::finalize ( )

Terminates this VM activity.

The thread creating the VM or the VM owner shall call this to inform the system that the VM will not be actvive anymore.

The VM will be destroyed immediately or as soon as all the other references are released.

This fucntion also dereference the VM once (in the behalf of the VM original owner).

Item* Falcon::VMachine::findGlobalItem ( const String & name ) const

Returns a live global given the name of its symbol.

Items exported by moduels becomes associated with an item that can be accessed (and then changed) by both scripts and modules extensions.

This method returns a pointer to the item that stores the current value of the given global symbol, and it is exactly the item that the scripts using that symbol are seeing.

The returned item is already dereferenced. Changing it will change all items referred by this symbol in all the modules.

Note:: To create failsafe new instances of classes or to access critical functions exported by modules, use findWKI().

Parameters:

name

the symbol to be searched.

Returns:: the global item associated with the symbol if found, or 0 if the item does not exist.

const SymModule* Falcon::VMachine::findGlobalSymbol ( const String & str ) const

Item* Falcon::VMachine::findLocalSymbolItem ( const String & symName ) const

Returns the value of a local variable.

Similar to findLocalVariable(), but will return only the item coresponding to the named symbol. The symName parameter must be already trimmed and corespond exactly to the name of a variable in the local context.

If the symbol is not found in the local symbol table, accessible global tables are searched in order of visibility.

If the variable cannot be found, 0 is returned.

Parameters:

symName

the symbol name to be found

Returns:: the physical pointer to the variable storage, or 0 on failure.

bool Falcon::VMachine::findLocalVariable	(	const String &	name,
		Item &	data
	)			const

Returns the value of a local variable.

This function searces for a variable in the local context, and eventually in the global context if not locally found. The function also parses accessors as the "." dot operator or the [] array access operator, but it doesn't support range accessors or function calls.

As the value of object accessor may be synthezized on the fly, the method cannot return a physical pointer; the value of the variable is flat-copied in the data parameter.

Parameters:

	name	the variable to be found.
	data	where to store the value if found.

Returns:: true if the value can be found, false otherwise.

LiveModule* Falcon::VMachine::findModule ( const String & name )

Find a linked module with a given name.

Returns a pointer to the linked live module if the name exists, or 0 if the named module doesn't exist.

Item* Falcon::VMachine::findWKI ( const String & name ) const

Returns a well known item.

A well known item is an item that does not phiscally resides in any module, and is at complete disposal of VM.

Usually, System relevant classes as Error, TimeStamp, Stream and so on are considered WKI.

Modules can declare their own WKIs so that they can safely retreive their own original live data that cannot be possibly transformed by scripts.

Modules just need to declare a symbol adding the Symbol::setWKI clause, and the VM will create a proper entry on link step. WKI items are created for the module, but a safe copy is also saved in another location.

WKI items have not to be exported, although they can.

Note:: the data is not deep-copied. WKI are prevented to be chaged in their nature, but their content can still be changed. Please, notice that both flat items and classes are read-only from a script standpoint, while strings, arrays, objects and dictionaries can have their contents changed.
The returned Well Known item is never to be de/referenced.

Parameters:

name

the WKI to be found

Returns:: 0 if a WKI with that name can't be found, a valid item pointer on success.

bool Falcon::VMachine::functionalEval	(	const Item &	itm,
		uint32	pcount = `0`,
		bool	retArray = `true`
	)

Evaluate the item in a functional context.

The function return either true or false, evaluating the item as a funcional token. # If the item is an array, it is recursively scanned. # If the item is a callable item (including callable arrayas), it is called and then the return value is evaluated in a non-functional context (plain evaluation). # In all the other cases, the item is evaluated in a non-functional context.

More simply, if the item is callable is called, and is result is checked for Falcon truth value. If not, it's simply checked.

The return value will be in regA(), and it's the "reduced" list of items.

The function returns true if it has to stop for frame evaluation, false if the caller can loop. When the function returns true, the caller must immediately return to the calling frame; in case it needs to continue processing, it must install a frame return handler to be called back when the frame created by functionalEval is done.

Parameters:

	itm	the item to be functionally evaluated.
	pcount	the number of parameters in the VM to be treated as evaluation parameters.
	retArray	true to force return of an evaluated array in case the input is not a Sigma sequence.

Returns:: false if the caller can proceed, true if it must return.

uint32 Falcon::VMachine::gcCheckLoops ( ) const [inline]

void Falcon::VMachine::gcCheckLoops ( uint32 cl ) [inline]

void Falcon::VMachine::gcEnable ( bool mode )

Enable the Garbage Collector requests on this VM.

If mode is false, the VM never checks for garbage collector requests to block operations for detailed inspections.

If mode is true, the VM periodically tells the GC that it is ready for inspection, and it is forced to honor block requests when memory gets critically high.

However, if the GC is disabled, the VM may be inspected if it volountarily enters the idle state (sleep or I/O calls).

Parameters:

mode

True to allow forced periodic inspections in case of need.

uint32 Falcon::VMachine::generation ( ) const

Return current generation.

Item* Falcon::VMachine::getBinding ( const String & bind ) const

Return the value associated with a binding symbol.

This function searches the given binding symbol name in the current binding context and in all the visible contexts (?).

If the function returns 0, the symbol is unbound.

Parameters:

bind

The binding symbol name.

Returns:: A valid non-dereferenced binding value or 0 if the symbol is unbound.

bool Falcon::VMachine::getCaller	(	const Symbol *&	sym,
		const Module *&	module
	)

Get the caller of the current symbol.

If the caller cannot be found (i.e. because the current symbol is called directly by the embedding program) the method returns false.

Parameters:

	sym	on success, will hold a pointer to the symbol that called the current symbol.
	module	on success, will hold a pointer to the module where the caller symbol resides.

Returns:: true on success, false on failure.

bool Falcon::VMachine::getCallerItem	(	Item &	caller,
		uint32	level = `0`
	)

Get the item that called the current symbol.

If the caller cannot be found (i.e. because the current symbol is called directly by the embedding program) the method returns false.

Parameters:

	item	on success, will hold the item (eventually the method) that originated the call.
	level	previous callers desired (0 is the first caller).

Returns:: true on success, false on failure.

const ContextList* Falcon::VMachine::getCtxList ( ) const [inline]

static VMachine* Falcon::VMachine::getCurrent ( ) [static]

Returns the currently running VM.

The Currently running VM is the VM currently in control of garbage collecting and item creation.

There can be only one current VM per thread; the value is stored in a thread specific variable.

Accessing it can be relatively heavy, so it is highly advised not tu use it except when absolutely necessary to know the current vm and the value is currently unknown.

Note:: Embedding applications are advised not to "corss VM", that is, not to nest call into different VMs in the same thread

CoreClass* Falcon::VMachine::getMetaClass ( int itemID ) [inline]

References fassert, and FLC_ITEM_COUNT.

int32 Falcon::VMachine::getNextNTD32 ( ) [inline, protected]

Returns the next NTD32 parameter, advancing the pointer to the next instruction.

References Falcon::VMContext::code(), and Falcon::VMContext::pc_next().

int64 Falcon::VMachine::getNextNTD64 ( ) [inline, protected]

Returns the next NTD64 parameter, advancing the pointer to the next instruction.

References Falcon::VMContext::code(), Falcon::loadInt64(), and Falcon::VMContext::pc_next().

Item* Falcon::VMachine::getNextTravVar ( ) [protected]

Gets the next item in a trav loop.

Item* Falcon::VMachine::getOpcodeParam ( register uint32 bc_pos ) [protected]

Gets the nth parameter of an opcode.

Item* Falcon::VMachine::getSafeBinding ( const String & bind )

Return the value associated with a binding symbol, or creates one if not found.

This function searches the given binding symbol name in the current binding context and in all the visible contexts (?). If the symbol is not found, it is created in the innermost visible context.

If the function returns 0, then there is no visible context.

Parameters:

bind

The binding symbol name.

Returns:: A valid non-dereferenced binding value or 0 if there is no visible context.

Service* Falcon::VMachine::getService ( const String & name )

Queries the VM for a published service.

If a service with the given name has been published, the VM will return it; otherwise returns 0.

Parameters:

name

the service to be published on this VM.

Returns:: the required service or 0.

const ContextList* Falcon::VMachine::getSleepingList ( ) const [inline]

CoreSlot* Falcon::VMachine::getSlot	(	const String &	slotName,
		bool	create = `true`
	)

Gets a slot for a given message.

If the slot doesn't exist, 0 is returned, unless create is set to true. In that case, the slot is created anew and returned.

void Falcon::VMachine::handleRaisedError ( Error * err ) [protected]

Decides what to do with an error incoming in the main loop.

Usually, this get either rethrown to the application or handled as an item down to the script.

Stack is eventually unrolled till the item handler is found.

void Falcon::VMachine::handleRaisedItem ( Item & value ) [protected]

Perform an item raise.

This implements the "raise" keyword or "RIS" opcode, that is, takes an item and sends it to the relevant catch in the call hierarcy.

If the item can't be caught by the current context, then it is eventually encapsulated in an error and thrown to the applicaiton with a C++ throw new Error*. If the item contains an instance of a Falcon Error class, the inner core Error* is taken and that is raised instead.

After this call, if the item or error could be caught by the script, the context is prepared to run the error handler at the very next VM loop.

Parameters:

value

The item to be raised, possibly but not necessarily derived from a Falcon level Error class.

void Falcon::VMachine::hasProcessStreams ( bool b ) [inline]

Indicastes if this VM has been given standard streams control or not.

VM in embedding applications hold generally streams that are not pointing to the process streams. Only direct itepreters (e.g. falcon command line) generally provides the VM with the process standard streams; normally, the process doesn't want the VM to use its standard stream, and even when it does, it doesn't want the VM (and the scripts) to be able to close the streams on its behalf.

This is however desirable when scripts are running in a standalone environment, so that they can interact with other piped processes. In that case, both embedding applications, but more generally script interpreters as falcon command line, will give full stream ownership to the VM, and let them to possibly close the streams directly.

Parameters:

b

set to true to allow the scripts on this VM to close standard streams.

bool Falcon::VMachine::hasProcessStreams ( ) const [inline]

void Falcon::VMachine::idle ( ) [inline]

Declares an IDLE section.

In code sections where the VM is idle, it is granted not to change its internal structure. This allow inspection from outer code, as i.e. the garbage collector.

Note:: Calls VM baton release (just candy grammar).

See also:: baton()

References Falcon::VMBaton::release().

void Falcon::VMachine::incref ( )

Increments the reference count for this VMachine.

void Falcon::VMachine::init ( )

Initialize the virutal machine.

Setups some configurable items that are used by the machine.

They are namely:

m_stdIn: standard input. The default is to use an instance returned by stdInputStream(), which interfaces a localized text version of process stdin.
m_stdOut: standard output. The default is to use an instance returned by stdOutputStream(), which interfaces a localized text version of process stdout.
m_stdErr: standard error. The default is to use an instance returned by stdErrorStream(), which interfaces a localized text version of process stderr. void terminateCurrentContext();

The subclass should set up its own items, if the default ones are not suitable, and then call the base class init(). The base init will not overwrite those items if they are valorized, but it may configure them to set up them properly, so it should always be called even if all the items are set by the subclass.

See also:: VMachine( bool )

void Falcon::VMachine::initializeInstance	(	const Symbol *	sym,
		LiveModule *	livemod
	)

Constructs an instance calling its _init method if necessary.

Instance construction must be performed after all the items are pre-linked, all the classes are formed and all the instances are set-up; in this way, it is possible for object _init method to refer to other objects, even if not yet initialized, as their structure is complete and coherent in the VM.

The VM may call either its own VM bytecode or external functions; calls are performed in non-atomic mode. This means that this method should not be called from functions executed by the VM, normally. If this is necessary, then the call of this method must be surrounded by setting and resetting the atomic mode.

Note:: Running in atomic mode doesn't mean "locking the VM"; the atomic mode is just a mode in which the VM runs without switching coroutines, accepting sleep requests or fulfilling suspension requests. Trying to suspend or prehempt the VM in atomic mode raises an unblockable exception, terminating the current script (and leaving it in a non-resumable status).

Parameters:

	sym	The class instance to be initialized.
	lmod	The live module where the symbol must go.

Exceptions:

Error

if the instance cannot be created.

void Falcon::VMachine::internal_construct ( ) [protected]

void Falcon::VMachine::interrupt ( ) [inline]

Interrupts pending I/O on this machine from a separate thread.

Interrupts compliant streams I/O and wait operations. The next I/O or the next wait, or the next compliant system blocking operation will cause an Interrupted exception to be raised.

This method does not generate an "interrupt request" on the VM, that will keep on running until a blocking operation is encountered.

This method can be safely called from other threads in the same application where the is currently executed, as well as from inside the same thread.

References Falcon::Sys::SystemData::interrupt().

bool Falcon::VMachine::interrupted	(	bool	raise = `false`,
		bool	reset = `false`,
		bool	dontCheck = `false`
	)

Returns true if the VM has been interrupted.

If an asynchronous interrupt has been generated, this method will return true.

This is meant to be called from those compliant operations that require polling, or just before starting waiting on interruptable code to avoid useless calculations, or right after to know if the VM has been interrupted during the computation.

Parameters:

	raise	if true, prepare an Interrupted exception in the VM context if the VM has been interrupted.
	reset	if true, reset interrupted status now.
	dontCheck	suppse interruption test is already done, and just raise the error and reset.

Returns:: true if the machine has been interrupted through interrupt() request.

bool Falcon::VMachine::isGcEnabled ( ) const

bool Falcon::VMachine::isParamByRef ( uint32 itemId ) const [inline]

Returns true if the nth element of the current function has been passed by reference.

Parameters:

itemId

the number of the parameter accessed, 0 based.

Returns:: true if the parameter exists and has been passed by reference, false otherwise

References FLC_ITEM_REFERENCE, Falcon::VMContext::stackBase(), and VM_FRAME_SPACE.

void Falcon::VMachine::itemToString	(	String &	target,
		const Item *	itm
	)			`[inline]`

void Falcon::VMachine::itemToString	(	String &	target,
		const Item *	itm,
		const String &	format
	)

Converts an item into a string.

The string is NOT added to the garbage collecting system, so it may be disposed freely by the caller. This translates into a direct call to Item::toString(), unless the item is an object. In that case, if the item provides a toString() method, then that method is called passing the "format" parameter (only if it's not empty).

Parameters:

	itm	a pointer to the item that must be represented as a string,
	format	a format that will be eventually sent to the "toString" method of the object.
	target	the output representation of the string

void Falcon::VMachine::jump ( uint32 pos ) [inline]

Change the position of the next executed instruction.

References Falcon::VMContext::pc_next().

Item& Falcon::VMachine::latch ( ) [inline]

Latch item.

Generated on load property/vector instructions, it stores the accessed object.

References Falcon::VMContext::latch().

const Item& Falcon::VMachine::latch ( ) const [inline]

Latch item.

Generated on load property/vector instructions, it stores the accessed object.

References Falcon::VMContext::latch().

Item& Falcon::VMachine::latcher ( ) [inline]

Latcher item.

Generated on load property/vector instructions, it stores the accessor item.

References Falcon::VMContext::latcher().

const Item& Falcon::VMachine::latcher ( ) const [inline]

Latcher item.

Generated on load property/vector instructions, it stores the accessor item.

References Falcon::VMContext::latcher().

void Falcon::VMachine::launch	(	const String &	startSym,
		uint32	paramCount = `0`
	)

Launches a routine.

This methods prepares the execution environment of the script by allocating the items that represents the global variables in the various modules. This step is called "realization" of the Runtime, as it provides a set of "real" (in the sense of effective) values for the items that are drawn in the library. This may be a relatively long step.

If the VM had been already used to launch a routine, the status and memory are cleaned and everything is returned to the startup state.

Then the routine whose name is given is searched in the top module (the one that has been added last to the runtime). If not found there, it is searched in the exported symbols of the whole runtime. If not given, the __main__ symbol of the top module is executed. If the required symbol cannot be found an error is raised and false is returned.

The routine returns true if execution is successful; the VM may return because the routine terminates, because of an explicit END opcode and because execution limit (single step or limited step count) is matched. Also, uncaught exceptions or explicit requests for termination may cause the VM to return.

It is possible to know if the execution is complete by looking at the last VM event with the lastEvent() method: if none or quit, then the execution is just terminated, else an event is set (i.e. tSuspend).

Parameters:

	startSym	the name of a routine to be executed.
	paramCount	Number of parameters that have been pushed in the stack as parameters.

Exceptions:

CodeError*

if the symbol to be launched couldn't be found.

void Falcon::VMachine::launch ( ) [inline]

Launches the "__main__" symbol.

This is a proxy call to launch( "__main__" );

References launch().

Referenced by launch().

bool Falcon::VMachine::launchAtLink ( ) const [inline]

Returns the launch-at-link mode.

This method returns true if the VM will launch the __main__ symbol of modules as soon as they are linked in the vm, or false otherwise.

void Falcon::VMachine::launchAtLink ( bool mode ) [inline]

Changes the status of launch-at-link mode.

uint32 Falcon::VMachine::limitLoops ( ) const [inline]

void Falcon::VMachine::limitLoops ( uint32 l ) [inline]

bool Falcon::VMachine::limitLoopsHit ( ) const [inline]

LiveModule* Falcon::VMachine::link	(	Module *	module,
		bool	isMainModule = `true`,
		bool	bPrivate = `false`
	)

Links a single module.

The last-linked module is usually set as the main module, but it is possible to link a non-main module.

After linking, the caller may release the reference if the module is needed only in this VM; the VM keeps a reference to the module.

The VM holds a reference to the module also in case of errors: the module may be still needed for error reports or debug. To destroy definitely the module, the VM must be destroyed or the module must be unlinked.

In case of link error, the error handler of the VM is signaled and the function returns false, otherwise it returns true. If the VM hasn't an error handler set, nothing is signaled, but the error is still available after return through exitError() method.

Note:: The main module is the module that is preferentially searched for start symbol(s) by prepare() function.

Parameters:

	rt	the runtime to be linked
	isMainModule	false to prevent this module to be chosen as startup module.
	bPrivate	false to allow this module to export the exported symbols, true to make the module private (and prevent exports).

Returns:: 0 time error, the internally built LiveModule instance on success.

LiveModule* Falcon::VMachine::link ( Runtime * rt )

Links a set of modules stored in a runtime.

The modules that have been loaded and pre-linked by the runtime are correctly inserted in the VM. The topmost module in the Runtime is set as main module.

After the link step, the runtime is not needed anymore and can be destroyed; the modules are safely referenced in the VM.

In case of link error, the error handler of the VM is signaled and the function returns false, otherwise it returns true. If the VM hasn't an error handler set, nothing is signaled, but the error is still available after return through exitError() method.

Note:: The main module is the module that is preferentially searched for start symbol(s) by prepare() function.

Parameters:

rt

the runtime to be linked

Returns:: The topmost module in the runtime turned into a livemoude, or zero on failure.

CoreClass* Falcon::VMachine::linkClass	(	LiveModule *	lmod,
		const Symbol *	clsym
	)

Creates a new class live item.

This function recursively resolves inheritences and constructor of classes to generate a "CoreClass", which is a template ready to create new instances.

Parameters:

	lmod	the live module (module + live data) where this class is generated
	clsym	the symbol where the class is defined.

bool Falcon::VMachine::linkClassSymbol	(	const Symbol *	sym,
		LiveModule *	livemod
	)

Links a class symbol.

Class symbols must be specially post-processed after all the other symbols (including themselves) are pre-linked, so that cross references can be resolved.

This method preforms the creation of a CoreClass that will reside in the live module passed as parameter.

In debug, an assert checks that the incoming symbol is a class. If dynamically called, the caller should check that sym is a real class symbol.

Parameters:

	sym	The class symbol to be linked.
	lmod	The live module where the symbol must go.

Returns:: false if the link fails, true on success.

bool Falcon::VMachine::linkCompleteSymbol	(	Symbol *	sym,
		const String &	moduleName
	)

Links a symbol eventually performing class and instances initializations.

This method resoves the module name into its liveMod before performing complete linking. This allows external elements (i.e. FALCON_FUNC methods) to create new symbols on the fly, declaring just into which module they should be created.

If the target module is not found the method returns false, otherwise it calls directly linkCompleteSymbol( Symbol *, LiveModule * ) with the appropriate instance of the LiveModule.

This method should run in atomic mode (see initializeInstance() ).

Parameters:

	sym	Symbol created dynamically.
	moduleName	name of the module that has created it and wants it to be inserted in the VM.

bool Falcon::VMachine::linkCompleteSymbol	(	const Symbol *	sym,
		LiveModule *	livemod
	)

Links a symbol eventually performing class and instances initializations.

This method should be called when incrementally adding symbol once is knonw that the classes and objects they refer to are (or should) be already linked in the VM, in already existing live modules.

This is the case of dynamic symbol creation in flexy modules, where the running scripts can create new symbols or invoke module actions that will create symbols; this is perfectly legal, but in that case the created instance will need to have everything prepared; cross references won't be resolved.

This also means that the caller willing to link completely a new instance symbol must first link it's referenced class.

This method should run in atomic mode (see initializeInstance() ).

bool Falcon::VMachine::linkDefinedSymbol	(	const Symbol *	sym,
		LiveModule *	lmod
	)			`[protected]`

bool Falcon::VMachine::linkInstanceSymbol	(	const Symbol *	sym,
		LiveModule *	livemod
	)

Links a class instance.

Class instances are what is commonly called "Singleton objects", declared through the "object" Falcon keyword.

Class instances must be specially post-processed after all the other symbols and class declarations are pre-linked, so that cross references can be resolved.

This method preforms the creation of a CoreClass that will reside in the live module passed as parameter.

In debug, an assert checks that the incoming symbol is a class. If dynamically called, the caller should check that sym is a real class symbol.

Parameters:

	sym	The instance symbol to be linked.
	lmod	The live module where the symbol must go.

Returns:: false if the link fails, true on success.

bool Falcon::VMachine::linkSubClass	(	LiveModule *	mod,
		const Symbol *	clssym,
		Map &	props,
		ObjectFactory *	factory
	)			`[protected]`

Service recursive function called by LinkClass to create a class.

bool Falcon::VMachine::linkSymbol	(	const Symbol *	sym,
		LiveModule *	lmod
	)

Links a single symbol on an already existing live module.

This won't actually link instances and classes which must be post-processed.

Parameters:

	sym	The symbol to be linked.
	lmod	The live module where the symbol must go.

Returns:: false if the link fails, true on success.

virtual bool Falcon::VMachine::linkSymbolDynamic	(	const String &	name,
		SymModule &	symdata
	)			`[virtual]`

Try to link a dynamic symbol.

This method asks the modules that can provide dynamic symbols if they are interested to serve us with a symbol for the given name. If so, the symbol is linked, and a complete reference to its position (SymModule) is returned.

The symbol needs not to be global to be exported this way. The providers may return private symbols that will be used just in this occasion and won't enter the global symbol map.

The method may raise any error that linkSymbolComplete may raise. The same cares used for LinkSymbolComplete void terminateCurrentContext(); should be used.

The method is virtual, so subclasses are able to create symbols dynamically by providing them directly. However, subclasses creating directly symbols must still create them inside a FlexyModule and use linkCompleteSymbol to bless the symbol in the VM.

It is advisable to call the base class version of the method on subclass default.

Parameters:

	name	The symbol to be searched for.
	symdata	Coordinates of the linked symbol, on success.

Returns:: true on success, false if the symbol is not found or if it was found but couldn't be linked.

bool Falcon::VMachine::linkUndefinedSymbol	(	const Symbol *	sym,
		LiveModule *	lmod
	)			`[protected]`

const LiveModuleMap& Falcon::VMachine::liveModules ( ) const [inline]

Return the map of live modules ordered by name (const version).

Returns:: the list of live (linked) modules.

LiveModuleMap& Falcon::VMachine::liveModules ( ) [inline]

Return the map of live modules ordered by name.

Returns:: the list of live (linked) modules.

Item* Falcon::VMachine::local ( uint32 itemId ) [inline]

Returns the nth local item.

This is just the non-const version. The first variable in the local context is numbered 0.

Parameters:

itemId

the number of the local item accessed.

Returns:: a valid pointer to the (dereferenced) local variable or 0 if itemId is invalid.

References Falcon::VMContext::local().

const Item* Falcon::VMachine::local ( uint32 itemId ) const [inline]

Returns the nth local item.

The first variable in the local context is numbered 0.

Note:: Fetched item pointers are valid while the stack doesn't change. Pushes, addLocal(), item calls and VM operations may alter the stack. Using this method again after such operations allows to get a valid pointer to the desired item again. Items extracted with this method can be also saved locally in an Item instance, at the cost of a a flat item copy (a few bytes).

Parameters:

itemId

the number of the local item accessed.

Returns:: a valid pointer to the (dereferenced) local variable or 0 if itemId is invalid.

References Falcon::VMContext::local().

LiveModule* Falcon::VMachine::mainModule ( ) const [inline]

Returns the main module, if it exists.

Returns an instance of the LiveModule class, that is the local representation of a module linked in the VM, that holds informations about the "main" module in this virtual machine.

void Falcon::VMachine::markSlots ( uint32 mark )

Used by the garbage collector to accunt for items stored as slot callbacks.

const Item& Falcon::VMachine::moduleItem ( uint32 pos ) const [inline]

Returns a reference to the nth item in the current module global variables vector (const version).

Item& Falcon::VMachine::moduleItem ( uint32 pos ) [inline]

Returns a reference to the nth item in the current module global variables vector.

const String& Falcon::VMachine::moduleString ( uint32 stringId ) const

Return current module string at given ID.

Retreives the module string which has been given the passed ID, and returns it to the caller. If the string is not found, a statically allocated empty string is returned instead.

Parameters:

stringId

the id for the string in the current module

virtual void Falcon::VMachine::onIdleTime ( numeric seconds ) [virtual]

Call back on sleep requests.

This method is called back when the virtual machine detects the need to perform a pause.

The default VMachine version calls the system "sleep" routine, but the application may find something more interesting to do.

Note:: The application should eventually call idle() and unidle() respectively at enter and exit of this callback if it doesn't use the VM while in this routine.

Parameters:

seconds

Number of seconds (and fractions) that the VM is idle.

Exceptions:

	InterruptedError	if the wait was interrupted.
	CodeError	if the wait is < 0 (infinite) and there are no active contexts able to wake up this one.

byte Falcon::VMachine::operandType ( byte opNum ) const [inline]

References Falcon::VMContext::code(), and Falcon::VMContext::pc().

Item* Falcon::VMachine::param ( uint32 itemId ) [inline]

Returns the nth paramter passed to the VM.

This is just the noncost version.

The count is 0 based (0 is the first parameter). If the parameter exists, a pointer to the Item holding the parameter will be returned. If the item is a reference, the referenced item is returned instead (i.e. the parameter is dereferenced before the return).

The pointer may be modified by the caller, but this will usually have no effect in the calling program unless the parameter has been passed by reference.

Note:: Fetched item pointers are valid while the stack doesn't change. Pushes, addLocal(), item calls and VM operations may alter the stack. Using this method again after such operations allows to get a valid pointer to the desired item. Items extracted with this method can be also saved locally in an Item instance, at the cost of a a flat item copy (a few bytes).

Parameters:

itemId

the number of the parameter accessed, 0 based.

Returns:: a valid pointer to the (dereferenced) parameter or 0 if itemId is invalid.

See also:: isParamByRef

References Falcon::VMContext::stackBase(), and VM_FRAME_SPACE.

const Item* Falcon::VMachine::param ( uint32 itemId ) const [inline]

Returns the nth paramter passed to the VM.

Const version of param(uint32).

References Falcon::VMContext::stackBase(), and VM_FRAME_SPACE.

int32 Falcon::VMachine::paramCount ( ) const [inline]

Returns the parameter count for the current function.

Note:: Calling this when the VM is not engaged in executing a function will crash.

Returns:: parameter count for the current function.

References VM_FRAME_SPACE.

Item* Falcon::VMachine::parseSquareAccessor	(	const Item &	accessed,
		String &	accessor
	)			const `[protected]`

void Falcon::VMachine::performGC ( bool bWaitForCollection = false )

Force a GC collection loop on the virtual machine.

Waits for the GC loop to be completed. The virtual machine must be in non-idle mode when calling this function, as the idle ownership is directly transferred to the GC and then back to the calling VM without interruption.

Normallym the GC will notify the VM back as soon as the mark loop is over; If the VM wants to wait for the free memory to be collected, set the parameter to true.

virtual void Falcon::VMachine::periodicCallback ( ) [virtual]

Periodic callback.

This is the periodic callback routine. Subclasses may use this function to get called every now and then to i.e. stop the VM asynchronously, or to perform debugging.

void Falcon::VMachine::periodicChecks ( ) [protected]

Performs periodic checks on the virtual machine.

void Falcon::VMachine::popTry ( bool moveTo )

Pop a try position, eventually changing the frame to the handler.

void Falcon::VMachine::postMessage ( VMMessage * vm )

Send a message to the VMachine.

If the virtual machine is currently idle, the message is immediately processed.

Otherwise, it is posted to the main VM loop, and it is executed as soon as possible.

The ownership of the message passes to the virtual machine, which will destroy it as the message is complete.

The message is processed by broadcasting on the coresponding VM slot.

LiveModule* Falcon::VMachine::prelink	(	Module *	mod,
		bool	bIsMain,
		bool	bPrivate
	)			`[protected]`

void Falcon::VMachine::prepareFrame	(	CoreArray *	ca,
		uint32	paramCount
	)

Prepare a frame for an array call.

The function oesn't check for the array to be callable because it's supposed that the check is on the caller.

However, a debug assert is performed.

void Falcon::VMachine::prepareFrame	(	CoreFunc *	cf,
		uint32	paramCount
	)

Prepare a frame for a function call.

void Falcon::VMachine::processMessage ( VMMessage * msg ) [protected]

Processes an incoming message.

This searches for the slot requierd by the message; if it is found, the message is broadcast to the slot in a newly created coroutine, otherwise the onMessageComplete is immedately called. void terminateCurrentContext(); The message will be immediately destroyed if it can't be broadcast.

Parameters:

msg

The message to be processed.

uint32 Falcon::VMachine::programCounter ( ) const [inline]

References Falcon::VMContext::pc().

void Falcon::VMachine::publishService ( Service * svr )

Publish a service.

Will raise an error and return false if the service is already published.

Parameters:

svr

the service to be published on this VM.

Exceptions:

CodeError

on dupilcated names.

void Falcon::VMachine::pushParameter ( const Item & item ) [inline]

Pushes a parameter for the vm callItem and callFrame functions.

See also:: callItem
callFrame

Parameters:

item

the item to be passes as a parameter to the next call.

References Falcon::VMContext::pushParameter().

void Falcon::VMachine::pushTry ( uint32 landingPC )

Push current try position.

void Falcon::VMachine::putAtSleep ( VMContext * ctx ) [protected]

Puts the given context at sleep.

This function inserts the given context in the sleep queue, inserting it in schedule order.

Contexts waiting forever are put at bottom; contexts not wishing to sleep are put at top.

void Falcon::VMachine::raiseHardError	(	int	code,
		const String &	expl,
		int32	line
	)			`[protected]`

void Falcon::VMachine::recallFrame ( ) [inline]

Prepare the VM to recall current return frame.

Calling this method and returning true, an handler set with returnFrame() can instruct the VM to call itself again after having performed a loop check.

Note:: This method must be called only inside extension functions, better if they are also return frame handlers.

See also:: callFrameNow()

References Falcon::VMContext::pc(), and Falcon::VMContext::pc_next().

void Falcon::VMachine::referenceItem	(	Item &	target,
		Item &	source
	)

Creates a reference to an item.

The source item is turned into a reference which is passed in the target item. If the source is already a reference, the reference is just passed in the target.

Parameters:

	target	the item that will accept reference to source
	source	the source item to be referenced

Item& Falcon::VMachine::regA ( ) [inline]

References Falcon::VMContext::regA().

const Item& Falcon::VMachine::regA ( ) const [inline]

References Falcon::VMContext::regA().

Item& Falcon::VMachine::regB ( ) [inline]

References Falcon::VMContext::regB().

const Item& Falcon::VMachine::regB ( ) const [inline]

References Falcon::VMContext::regB().

Item& Falcon::VMachine::regBind ( ) [inline]

References Falcon::VMContext::regBind().

const Item& Falcon::VMachine::regBind ( ) const [inline]

References Falcon::VMContext::regBind().

Item& Falcon::VMachine::regBindP ( ) [inline]

References Falcon::VMContext::regBindP().

const Item& Falcon::VMachine::regBindP ( ) const [inline]

References Falcon::VMContext::regBindP().

void Falcon::VMachine::removeSlot ( const String & slotName )

Removes and dereference a message slot in the VM.

void Falcon::VMachine::requestConstruct ( ) [inline]

Request a constructor call after a call frame.

If the preceding callFrame() was directed to an external function, requests the VM to treat the return value as an init() return, placing self() in regA() when all is done.

References Falcon::VMContext::pc_next().

void Falcon::VMachine::reschedule ( VMContext * ctx ) [protected]

Resort this context changing its position in the sleep list.

Actually, this function works as putAtSleep(), but it continues to scan the sleeping context sleep till it finds the previous position of the context to remove it.

void Falcon::VMachine::reset ( )

Reset machine for a clean execution.

This resets the VM to execute cleanly a ascript, removing all the dirty variables, execution context and the rest.

void Falcon::VMachine::resetCounters ( )

void Falcon::VMachine::retnil ( ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setNil().

ext_func_frame_t Falcon::VMachine::returnHandler ( )

Returns currently installed return handler, or zero if none.

Returns:: currently installed return handler, or zero if none.

ext_func_frame_t Falcon::VMachine::returnHandler ( ) const [inline]

References Falcon::VMContext::returnHandler().

void Falcon::VMachine::returnHandler ( ext_func_frame_t callbackFunc ) [inline]

Installs a post-processing return frame handler.

The function passed as a parmeter will receive a pointer to this VM.

The function MUST return true if it performs another frame item call. This will tell the VM that the stack cannot be freed now, as a new call stack has been prepared for immediate execution. When done, the function will be called again.

A frame handler willing to call another frame and not willing to be called anymore must first unininstall itself by calling this method with parameters set at 0, and then it MUST return true.

A frame handler not installing a new call frame MUST return false. This will terminate the current stack frame and cause the VM to complete the return stack.

Parameters:

callbackFunct

the return frame handler, or 0 to disinstall a previously set handler.

References Falcon::VMContext::returnHandler().

void Falcon::VMachine::retval ( const String & cs ) [inline]

References Falcon::String::bufferize(), Falcon::VMContext::regA(), and Falcon::Item::setString().

void Falcon::VMachine::retval ( CoreClass * cc ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setClass().

void Falcon::VMachine::retval ( CoreObject * co ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setObject().

void Falcon::VMachine::retval ( CoreDict * cd ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setDict().

void Falcon::VMachine::retval ( MemBuf * mb ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setMemBuf().

void Falcon::VMachine::retval ( CoreArray * ca ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setArray().

void Falcon::VMachine::retval ( CoreString * cs ) [inline]

Returns a garbageable string.

Note:: to put a nongarbage string in the VM use regA() accessor, but you must know what you're doing.

References Falcon::VMContext::regA(), and Falcon::Item::setString().

void Falcon::VMachine::retval ( String * cs ) [inline]

Returns a non garbageable string.

References Falcon::VMContext::regA(), and Falcon::Item::setString().

void Falcon::VMachine::retval ( const Item & val ) [inline]

References Falcon::VMContext::regA().

void Falcon::VMachine::retval ( numeric val ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setNumeric().

void Falcon::VMachine::retval ( int64 val ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setInteger().

void Falcon::VMachine::retval ( int32 val ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setInteger().

void Falcon::VMachine::retval ( bool val ) [inline]

References Falcon::VMContext::regA(), and Falcon::Item::setBoolean().

void Falcon::VMachine::rotateContext ( )

void Falcon::VMachine::run ( )

Virtual machine main loop.

This is the method that is responsible for the main virtual machine loop. The VM can be configured to run a limited number of steps (or even one); there are also several other settings that may affect the run behavior.

Usually, the user program won't call this; the launch() method sets up the execution environment and then calls run(). Calling this method is useful to continue a pending execution (including single step execution).

If a symbol name is provided, then the symbol is executed retaining all the current status. The symbol is searched in the locals of the top module, and then in the global of the runtime eaxtly as for launch(). This is useful, for example, to provide callback entry points in scripts that must maintain their execution status between calls. In this way, each run maintain the previous status but grants execution of different entry points; also this is quite faster than having to enter the realization phase.

An error will be risen if launch has not been previously called and the routine name is not provided.

bool Falcon::VMachine::seekInRange	(	int64	num,
		byte *	base,
		uint16	size,
		uint32 &	landing
	)			const `[protected]`

Utility for switch opcode.

Just pretend it's not here.

bool Falcon::VMachine::seekInteger	(	int64	num,
		byte *	base,
		uint16	size,
		uint32 &	landing
	)			const `[protected]`

Utility for switch opcode.

Just pretend it's not here.

bool Falcon::VMachine::seekItem	(	const Item *	item,
		byte *	base,
		uint16	size,
		uint32 &	landing
	)			`[protected]`

Utility for switch opcode.

Just pretend it's not here.

bool Falcon::VMachine::seekItemClass	(	const Item *	obj,
		byte *	base,
		uint16	size,
		uint32 &	landing
	)			const `[protected]`

Utility for select opcode.

Just pretend it's not here.

bool Falcon::VMachine::seekString	(	const String *	str,
		byte *	base,
		uint16	size,
		uint32 &	landing
	)			const `[protected]`

Utility for switch opcode.

Just pretend it's not here.

Item& Falcon::VMachine::self ( ) [inline]

References Falcon::VMContext::self().

const Item& Falcon::VMachine::self ( ) const [inline]

References Falcon::VMContext::self().

bool Falcon::VMachine::setBinding	(	const String &	bind,
		const Item &	value
	)

Set a binding value.

This function sets a binding value in the current context. If a binding context has not been set, the function returns false.

Parameters:

	bind	The binding symbol name.
	value	The value to associate to this binding.

void Falcon::VMachine::setBindingContext ( CoreDict * ctx ) [inline]

Set current binding context.

The current binding context is a dictionary containing a set of bound symbols and their value (referenced).

Binding context is NOT GC masked, so it must exist elsewhere (i.e. in a live dictionary).

The binding context is automatically removed at frame return.

References Falcon::VMContext::regBind().

void Falcon::VMachine::setCurrent ( ) const [protected]

Sets the currently running VM.

The Currently running VM is the VM currently in control of garbage collecting and item creation.

There can be only one current VM per thread; the value is stored in a thread specific variable.

Accessing it can be relatively heavy, so it is highly advised not tu use it except when absolutely necessary to know the current vm and the value is currently unknown.

Note:: Embedding applications are advised not to "corss VM", that is, not to nest call into different VMs in the same thread

void Falcon::VMachine::setFinalizeCallback ( void(*)(VMachine *vm) finfunc ) [inline]

Finalization callback function (used by MT).

void Falcon::VMachine::setMetaClass	(	int	itemID,
		CoreClass *	metaClass
	)			`[inline]`

References fassert, and FLC_ITEM_COUNT.

void Falcon::VMachine::setupScript	(	int	argc,
		char **	argv
	)

Setup the main script standard parameters and variables.

This is an utility function filling the follwing global variables, provided they have been linked and are globally exported from some module in the VM:

script_name: the logical module name of the main module.
script_path: physical path of the main module.
args: filled with argc and argv.

bool Falcon::VMachine::singleStep ( ) const [inline]

void Falcon::VMachine::singleStep ( bool ss ) [inline]

const ItemArray& Falcon::VMachine::stack ( ) const [inline]

Returns the current stack as a reference (const version).

References Falcon::VMContext::stack().

ItemArray& Falcon::VMachine::stack ( ) [inline]

Returns the current stack as a reference.

References Falcon::VMContext::stack().

uint32& Falcon::VMachine::stackBase ( ) [inline]

References Falcon::VMContext::stackBase().

const uint32& Falcon::VMachine::stackBase ( ) const [inline]

References Falcon::VMContext::stackBase().

const Item& Falcon::VMachine::stackItem ( uint32 pos ) const [inline]

Returns a reference to the nth item in the current stack (const version).

Item& Falcon::VMachine::stackItem ( uint32 pos ) [inline]

Returns a reference to the nth item in the current stack.

void Falcon::VMachine::stdErr ( Stream * nstream )

Set stdandard error stream.

Old standard error stream abstraction is destroyed (vm owns it).

Note:: This doesn't changes the stream used by the standard error handler, which, by default, is set to a owned copy of this stream.

See also:: stdOut()

Parameters:

nstream

the new stream

Stream* Falcon::VMachine::stdErr ( ) const [inline]

Gets the standard input stream associated with this VM.

VM may offer this stream to RTL and module functions wishing to print error messages.

By default, it is pointing to a correctly internationalized verisons of text-oriented Stream Transcoders. The transcoder is selected depending on the system environmental conditions, but there is no particular reason to use a transcoder instead of a direct stream, if this vm and functions using the standard streams abstractions held in the VM are willingt to operate on binary streams or on streams with different encodings.

Note:: the VM uses the default std error stream to feed the standard Default Error Handler at its creation. That handler has its own copy of a StdErrorStream implementation, and changing this object won't affect the default error handler. If the error handler output has to be redirected as well, the new stream must be directly set. Also, be sure not to give ownership of the stream to the default handler, as giving ownership would cause the handler AND the VM to try to destroy the same pointer.

Returns:: current incarnation of standard error stream.

void Falcon::VMachine::stdIn ( Stream * nstream )

Set stdandard input stream.

Old standard input stream abstraction is destroyed (vm owns it).

See also:: stdIn()

Parameters:

nstream

the new stream

Stream* Falcon::VMachine::stdIn ( ) const [inline]

Gets the standard input stream associated with this VM.

VM may offer this stream to RTL and module functions wishing to get some input (as, i.e., input() ).

By default, it is pointing to a correctly internationalized verisons of text-oriented Stream Transcoders. The transcoder is selected depending on the system environmental conditions, but there is no particular reason to use a transcoder instead of a direct stream, if this vm and functions using the standard streams abstractions held in the VM are willingt to operate on binary streams or on streams with different encodings.

Returns:: current incarnation of standard input stream.

void Falcon::VMachine::stdOut ( Stream * nstream )

Set stdandard output stream.

Old standard output stream abstraction is destroyed (vm owns it).

See also:: stdOut()

Parameters:

nstream

the new stream

Stream* Falcon::VMachine::stdOut ( ) const [inline]

Gets the standard input stream associated with this VM.

VM may offer this stream to RTL and module functions wishing to write generic output, as print, printl and inspect.

By default, it is pointing to a correctly internationalized verisons of text-oriented Stream Transcoders. The transcoder is selected depending on the system environmental conditions, but there is no particular reason to use a transcoder instead of a direct stream, if this vm and functions using the standard streams abstractions held in the VM are willingt to operate on binary streams or on streams with different encodings.

Returns:: current incarnation of standard output stream.

void Falcon::VMachine::step ( ) [inline]

Performs a single VM step and return.

References Falcon::VMContext::pc(), and Falcon::VMContext::pc_next().

Sys::SystemData& Falcon::VMachine::systemData ( ) [inline]

Get System Specific data (non const).

Returns:: system specific data bound with this machine.

const Sys::SystemData& Falcon::VMachine::systemData ( ) const [inline]

Get System Specific data.

Returns:: system specific data bound with this machine.

void Falcon::VMachine::terminateCurrentContext ( )

const uint32& Falcon::VMachine::tryFrame ( ) const [inline]

Returns the current try frame as a reference (const version).

References Falcon::VMContext::tryFrame().

uint32& Falcon::VMachine::tryFrame ( ) [inline]

Returns the current try frame as a reference.

References Falcon::VMContext::tryFrame().

void Falcon::VMachine::unbindItem	(	const String &	name,
		Item &	tgt
	)			const

Unbinds a late binding on the given target.

If the lbind item is not a late binding, tgt is copied from this item. If lbind is a literal late binding, returns a non-literal late binding. If lbind is a non-literal late binding tries to resolve the late binding; in success placese the bound item (by value) in tgt.

void Falcon::VMachine::unidle ( ) [inline]

Declares the end of an idle code section.

Note:: Calls VM baton acquire (just candy grammar).

See also:: baton()

References Falcon::Baton::acquire().

bool Falcon::VMachine::unlink ( const Module * module )

Unlinks a module.

The unlinked module become unavailable, and all the callable items referencing symbols in the module become uncallable. Exported global variables survive unlinking, and their value can still be inspected, modified and discarded after they have been unlinked.

It is not possible to unlink a module which is currently being run (that is, which is the module holding the currently executed symbol).

It is possible to unlink the main module, but a new main module won't be automatically elected; unless the start symbol is exported by other modules, prepare() will fail if a new main module is not linked in the VM.

The function may return false either if the module is not present in the VM or if it is the "current module".

Parameters:

module

the module to be unlinked.

Returns:: true on success, false on error.

bool Falcon::VMachine::unlink ( const Runtime * rt )

Unlinks all the modules in the runtime.

The unlinked module(s) become unavailable, and all the callable items referencing symbols in the module become uncallable. Exported global variables survive unlinking, and their value can still be inspected, modified and discarded after they have been unlinked.

It is not possible to unlink a module which is currently being run (that is, which is the module holding the currently executed symbol).

It is possible to unlink the main module, but a new main module won't be automatically elected; unless the start symbol is exported by other modules, prepare() will fail if a new main module is not linked in the VM.

The function may return false either if one of the module in the runtime is not present in the VM or if one of them is the "current module". However, some of the modules may have got unlinked int he meanwhile, and unlinking also dereferences them.

Parameters:

rt

the runtime with all the modules to be unlinked

Returns:: true on success, false on error.

void* Falcon::VMachine::userData ( ) const [inline]

Get the user data associated with this VM.

See also:: userData( void * )

Returns:: the previously set user data or 0 if user data is not set.

void Falcon::VMachine::userData ( void * ud ) [inline]

Set user data.

VM is passed to every extension function, and is also quite used by the embedding application. To provide application specific per-vm data to the scripts, the best solution for embedding applications is usually to extend the VM into a subclass. Contrarily, middleware extensions, as, for example, script plugins for applications, may prefer to use the standard Falcon VM and use this pointer to store application specific data.

The VM makes no assumption on the kind of user data. The data is not destroyed at VM destruction. If there is the need to destroy the data at VM destruction, then VM derivation seems a more sensible choice.

Parameters:

ud

the application specific user data.

void Falcon::VMachine::yield ( numeric seconds )

Make this context to sleep and elect a new one.

If no other context can be elected, the VM may issue an onIdleTime() and eventually sleep a bit.

Friends And Related Function Documentation

friend class MemPool [friend]

void opcodeHandler_ADD ( register VMachine * vm ) [friend]

void opcodeHandler_ADDS ( register VMachine * vm ) [friend]

void opcodeHandler_AND ( register VMachine * vm ) [friend]

void opcodeHandler_ANDS ( register VMachine * vm ) [friend]

void opcodeHandler_BAND ( register VMachine * vm ) [friend]

void opcodeHandler_BNOT ( register VMachine * vm ) [friend]

void opcodeHandler_BOOL ( register VMachine * vm ) [friend]

void opcodeHandler_BOR ( register VMachine * vm ) [friend]

void opcodeHandler_BXOR ( register VMachine * vm ) [friend]

void opcodeHandler_CALL ( register VMachine * vm ) [friend]

void opcodeHandler_CLOS ( register VMachine * vm ) [friend]

void opcodeHandler_DEC ( register VMachine * vm ) [friend]

void opcodeHandler_DECP ( register VMachine * vm ) [friend]

void opcodeHandler_DIV ( register VMachine * vm ) [friend]

void opcodeHandler_DIVS ( register VMachine * vm ) [friend]

void opcodeHandler_END ( register VMachine * vm ) [friend]

End opcode handler.

END opcode terminates current coroutine or current virtual machine execution.

void opcodeHandler_EQ ( register VMachine * vm ) [friend]

void opcodeHandler_EVAL ( register VMachine * vm ) [friend]

void opcodeHandler_FORB ( register VMachine * vm ) [friend]

void opcodeHandler_FORK ( register VMachine * vm ) [friend]

void opcodeHandler_GE ( register VMachine * vm ) [friend]

void opcodeHandler_GENA ( register VMachine * vm ) [friend]

void opcodeHandler_GEND ( register VMachine * vm ) [friend]

void opcodeHandler_GENR ( register VMachine * vm ) [friend]

void opcodeHandler_GEOR ( register VMachine * vm ) [friend]

void opcodeHandler_GT ( register VMachine * vm ) [friend]

void opcodeHandler_IFF ( register VMachine * vm ) [friend]

void opcodeHandler_IFT ( register VMachine * vm ) [friend]

void opcodeHandler_IN ( register VMachine * vm ) [friend]

void opcodeHandler_INC ( register VMachine * vm ) [friend]

void opcodeHandler_INCP ( register VMachine * vm ) [friend]

void opcodeHandler_INDI ( register VMachine * vm ) [friend]

void opcodeHandler_INST ( register VMachine * vm ) [friend]

void opcodeHandler_IPOP ( register VMachine * vm ) [friend]

void opcodeHandler_JMP ( register VMachine * vm ) [friend]

void opcodeHandler_JTRY ( register VMachine * vm ) [friend]

void opcodeHandler_LD ( register VMachine * vm ) [friend]

void opcodeHandler_LDAS ( register VMachine * vm ) [friend]

void opcodeHandler_LDP ( register VMachine * vm ) [friend]

void opcodeHandler_LDPT ( register VMachine * vm ) [friend]

void opcodeHandler_LDRF ( register VMachine * vm ) [friend]

void opcodeHandler_LDV ( register VMachine * vm ) [friend]

void opcodeHandler_LDVT ( register VMachine * vm ) [friend]

void opcodeHandler_LE ( register VMachine * vm ) [friend]

void opcodeHandler_LNIL ( register VMachine * vm ) [friend]

void opcodeHandler_LSB ( register VMachine * vm ) [friend]

void opcodeHandler_LSTA ( register VMachine * vm ) [friend]

void opcodeHandler_LT ( register VMachine * vm ) [friend]

void opcodeHandler_LVAL ( register VMachine * vm ) [friend]

void opcodeHandler_MOD ( register VMachine * vm ) [friend]

void opcodeHandler_MODS ( register VMachine * vm ) [friend]

void opcodeHandler_MUL ( register VMachine * vm ) [friend]

void opcodeHandler_MULS ( register VMachine * vm ) [friend]

void opcodeHandler_NEG ( register VMachine * vm ) [friend]

void opcodeHandler_NEQ ( register VMachine * vm ) [friend]

void opcodeHandler_NOIN ( register VMachine * vm ) [friend]

void opcodeHandler_NOP ( register VMachine * vm ) [friend]

void opcodeHandler_NOT ( register VMachine * vm ) [friend]

void opcodeHandler_NOTS ( register VMachine * vm ) [friend]

void opcodeHandler_ONCE ( register VMachine * vm ) [friend]

void opcodeHandler_OOB ( register VMachine * vm ) [friend]

void opcodeHandler_OR ( register VMachine * vm ) [friend]

void opcodeHandler_ORS ( register VMachine * vm ) [friend]

void opcodeHandler_PASS ( register VMachine * vm ) [friend]

void opcodeHandler_PEEK ( register VMachine * vm ) [friend]

void opcodeHandler_POP ( register VMachine * vm ) [friend]

void opcodeHandler_POW ( register VMachine * vm ) [friend]

void opcodeHandler_POWS ( register VMachine * vm ) [friend]

void opcodeHandler_PROV ( register VMachine * vm ) [friend]

void opcodeHandler_PSHL ( register VMachine * vm ) [friend]

void opcodeHandler_PSHN ( register VMachine * vm ) [friend]

void opcodeHandler_PSHR ( register VMachine * vm ) [friend]

void opcodeHandler_PSIN ( register VMachine * vm ) [friend]

void opcodeHandler_PTRY ( register VMachine * vm ) [friend]

void opcodeHandler_PUSH ( register VMachine * vm ) [friend]

void opcodeHandler_RET ( register VMachine * vm ) [friend]

void opcodeHandler_RETA ( register VMachine * vm ) [friend]

void opcodeHandler_RETV ( register VMachine * vm ) [friend]

void opcodeHandler_RIS ( register VMachine * vm ) [friend]

void opcodeHandler_SELE ( register VMachine * vm ) [friend]

void opcodeHandler_SHL ( register VMachine * vm ) [friend]

void opcodeHandler_SHLS ( register VMachine * vm ) [friend]

void opcodeHandler_SHR ( register VMachine * vm ) [friend]

void opcodeHandler_SHRS ( register VMachine * vm ) [friend]

void opcodeHandler_SSTA ( register VMachine * vm ) [friend]

void opcodeHandler_STEX ( register VMachine * vm ) [friend]

void opcodeHandler_STO ( register VMachine * vm ) [friend]

void opcodeHandler_STP ( register VMachine * vm ) [friend]

void opcodeHandler_STPR ( register VMachine * vm ) [friend]

void opcodeHandler_STPS ( register VMachine * vm ) [friend]

void opcodeHandler_STV ( register VMachine * vm ) [friend]

void opcodeHandler_STVR ( register VMachine * vm ) [friend]

void opcodeHandler_STVS ( register VMachine * vm ) [friend]

void opcodeHandler_SUB ( register VMachine * vm ) [friend]

void opcodeHandler_SUBS ( register VMachine * vm ) [friend]

void opcodeHandler_SVAL ( register VMachine * vm ) [friend]

void opcodeHandler_SWCH ( register VMachine * vm ) [friend]

void opcodeHandler_TRAC ( register VMachine * vm ) [friend]

void opcodeHandler_TRAL ( register VMachine * vm ) [friend]

void opcodeHandler_TRAN ( register VMachine * vm ) [friend]

void opcodeHandler_TRAV ( register VMachine * vm ) [friend]

void opcodeHandler_TRDN ( register VMachine * vm ) [friend]

void opcodeHandler_TRY ( register VMachine * vm ) [friend]

void opcodeHandler_WRT ( register VMachine * vm ) [friend]

void opcodeHandler_XORS ( register VMachine * vm ) [friend]

void opcodeHandler_XPOP ( register VMachine * vm ) [friend]

friend class VMContext [friend]

friend class VMSemaphore [friend]

Member Data Documentation

bool Falcon::VMachine::m_allowYield [protected]

Wether or not to allow a VM hostile takeover of the current context.

String Falcon::VMachine::m_appSearchPath [protected]

filtered load path

VMBaton Falcon::VMachine::m_baton [protected]

Main synchronization baton.

bool Falcon::VMachine::m_bGcEnabled [protected]

If true, the VM allows to be blocked periodically by the GC in case of need.

If false, the VM is left alone, and in case it becomes the VM having taken a GC scan for the last, its GC data gets promoted only if the GC enters the active state.

bool Falcon::VMachine::m_bhasStandardStreams [protected]

bool Falcon::VMachine::m_bPirorityGC [protected]

Event set by the VM to ask for priority GC.

This is used by the performGC() function to inform the GC loop about the priority of this VM.

bool Falcon::VMachine::m_bSingleStep [protected]

True for single stepping.

bool Falcon::VMachine::m_bWaitForCollect [protected]

True when we want to wait for collection before being notified in priority scans.

ContextList Falcon::VMachine::m_contexts [protected]

Ready to run contexts.

VMContext* Falcon::VMachine::m_currentContext [protected]

Context currently being executed.

Event Falcon::VMachine::m_eGCPerformed [protected]

Event set by the GC to confirm the forced GC loop is over.

uint32 Falcon::VMachine::m_generation [protected]

Generation at which the garbage data in this VM is marked.

SymModuleMap Falcon::VMachine::m_globalSyms [protected]

Map of global symbols (and the item they are connected to).

Each item of the map contains a Symbol * and an ID that allows to

VMachine* Falcon::VMachine::m_idleNext [protected]

VMachine* Falcon::VMachine::m_idlePrev [protected]

Item Falcon::VMachine::m_imm[4] [protected]

Space for immediate operands.

bool Falcon::VMachine::m_launchAtLink [protected]

Execute at link time?

LiveModuleMap Falcon::VMachine::m_liveModules [protected]

Map of live modules.

Todo: better docs.

GarbageLock* Falcon::VMachine::m_lockRoot [protected]

Locked and unreclaimable items are stored in this ring.

-- unused; kept for binary compatibilty

uint32 Falcon::VMachine::m_loopsCallback [protected]

Timeout for Callbacks.

uint32 Falcon::VMachine::m_loopsContext [protected]

Timeout for Context checks.

uint32 Falcon::VMachine::m_loopsGC [protected]

Timeout for GC collection.

LiveModule* Falcon::VMachine::m_mainModule [protected]

Main module.

This is the last linked module, that should also be the module where to search for start symbols; by default, launch() searches symbol here, and if not found, they search start symbols in globally exported symbol tables.

CoreClass** Falcon::VMachine::m_metaClasses [protected]

VMMessage* Falcon::VMachine::m_msg_head [protected]

VMMessage* Falcon::VMachine::m_msg_tail [protected]

Mutex Falcon::VMachine::m_mtx [mutable, protected]

Mutex Falcon::VMachine::m_mtx_lockitem [protected]

Mutex for locked items ring.

-- unused; kept for binary compatibilty

Mutex Falcon::VMachine::m_mtx_mesasges [protected]

VMachine* Falcon::VMachine::m_nextVM [protected]

void(* Falcon::VMachine::m_onFinalize)(VMachine *vm) [protected]

Finalization hook for MT system.

uint32 Falcon::VMachine::m_opCount [protected]

Number of opcodes that the current coroutine has performed.

tOpcodeHandler* Falcon::VMachine::m_opHandlers [protected]

Opcode handler function calls.

uint32 Falcon::VMachine::m_opLimit [protected]

Maximum operations that can be performed.

uint32 Falcon::VMachine::m_opNextCallback [protected]

uint32 Falcon::VMachine::m_opNextCheck [protected]

Smaller check in op loops.

uint32 Falcon::VMachine::m_opNextContext [protected]

uint32 Falcon::VMachine::m_opNextGC [protected]

VMachine* Falcon::VMachine::m_prevVM [protected]

volatile int Falcon::VMachine::m_refcount [protected]

Reference count.

Usually, shouldn't be very high: the caller program, the GC and possibly some extra method in embedding applications.

Map Falcon::VMachine::m_services [protected]

Subscribed services map.

Services are allocated in the respective module. Currently, there's no way to remove a module from a VM once it's linked, so there's no need for a special de-subscription mechanism.

Of course, if/when an unlink method is added, the module should also de-subscribe its services.

ContextList Falcon::VMachine::m_sleepingContexts [protected]

Contexts willing to sleep for a while.

Mutex Falcon::VMachine::m_slot_mtx [mutable, protected]

Mutex guarding the slot structure.

Map Falcon::VMachine::m_slots [protected]

Stream* Falcon::VMachine::m_stdErr [protected]

Stream* Falcon::VMachine::m_stdIn [protected]

Stream* Falcon::VMachine::m_stdOut [protected]

Sys::SystemData Falcon::VMachine::m_systemData [protected]

System specific data.