Falcon::Runtime Class Reference

Runtime code representation. More...

#include <runtime.h>

Inheritance diagram for Falcon::Runtime:

List of all members.

Public Member Functions

void addModule (Module *mod, bool bIsPrivate=false)

Adds a module to the Runtime library.

Module * findModule (const String &name)

Returns a module with the given name.

Module * findModuleByID (uint32 id)

Return the nth module.

void hasMainModule (bool b)

Changes the relevance of this runtime.

bool hasMainModule () const

Returns true if this loader top module is the main module for a final application.

bool hasPendingModules () const

Returns true if there are still some pending modules.

void loadFile (const String &file, bool bIsPrivate=false)

Loads the given module and adds it to the runtime.

void loadName (const String &name, const String &parent="", bool bIsPrivate=false)

Loads the given module and adds it to the runtime.

const ModuleMap * moduleMap () const

Return the symbol tably containing the global symbols.

const ModuleVector * moduleVector () const

Return the modules linked in this runtime.

Runtime ()

Creates the runtime.

Runtime (ModuleLoader *loader, VMachine *provider=0)

Creates the runtime and allows module load requests.

uint32 size ()

Return the amount of modules in this runtime.

bool willLoad ()

Tell wether this runtime tries to interpret the module load requests or just denies them.

~Runtime ()

Destroy this Runtime.

Detailed Description

Runtime code representation.

A runtime object represents a set of module that constitutes the existing runtime library. Two basic operations can be done on a runtime set: module addition and linking.

A runtime module is given a runtime error manager to inform the calling application about errors during module addition and linking (mainly, load failure ).

If provided with a ModuleLoader instance, the Runtime instance will ask the module loader to load any module that the given modules require to import, unless already present in the module set; else, the calling application must provide the modules to the Runtime one by one. This allows to put the embedding application in complete control of what modules may be loaded and how, and allows it to provide its own internal modules instead of the required ones.

At the moment, the modules must be pre-compiled in hsc format, but in future the module loader may detect if a module is given in source and compile it if the hsc is not present; this is a behavior bound in the module loader.

Todo:: In future, this class may support serialization to store the linked modules on disk, so that it may become a somewhat complete linker.

Constructor & Destructor Documentation

Falcon::Runtime::Runtime	(	ModuleLoader *	loader,
		VMachine *	provider = `0`
	)

Creates the runtime and allows module load requests.

Using this version of the constructor, the runtime will try to resolve module load requests that are embedded in each module before trying to link given modules.

An error manager can be specified later on with errorHandler().

The error manager is used to feedback the calling application or the user with rilevant error codes (i.e. the module loading faulire, symbol duplication or missing externals).

Neither the error manager nor the module loader are deleted at Runtime object deletion.

Parameters:

	loader	a module loader that will be used to load modules when they are required by other modules at link() time.
	provider	a virtual machine where the runtime must be linked later on.

Falcon::Runtime::Runtime ( )

Creates the runtime.

Using this version of the constructor, the runtime will not load any module that may be defined in the dependency list during the link phase; the calling application must load or provide the modules on its behalf and feed them in the link() method before the subsequesing modules require some symbols as external.

An error manager can be specified later on with errorHandler().

The error manager is used to feedback the calling application or the user with rilevant error codes (i.e. the module loading faulire, symbol duplication or missing externals).

The error manager is not deleted at Runtime object deletion.

Falcon::Runtime::~Runtime ( )

Destroy this Runtime.

When a runtime is destroyed, modules linked by this runtime are de-referenced and eventually destroyed. To save modules after their last runtime released them, add an Module::incref() call soon after their creation.

Member Function Documentation

void Falcon::Runtime::addModule	(	Module *	mod,
		bool	bIsPrivate = `false`
	)

Adds a module to the Runtime library.

This function adds a module to the runtime library and then it links it in two steps.

When a module is added to the runtime, its reference count is incremented, and a record containing its ID (relative position) is added. The ID will soft-link the module with its own global variable representation in the executing VM (i.e. Module N will have global variable vector number N, module K will refer to variables in the K vector and so on).

Parameters:

	mod	The module to be added.
	bIsPrivate	false (default) when linking requires exported symbols to be published globally in the VM.

Exceptions:

Error

on compilation/load error.

Module* Falcon::Runtime::findModule ( const String & name ) [inline]

Returns a module with the given name.

Or zero if the module with the required name is not found.

Module* Falcon::Runtime::findModuleByID ( uint32 id ) [inline]

Return the nth module.

void Falcon::Runtime::hasMainModule ( bool b ) [inline]

Changes the relevance of this runtime.

If the runtime "has the main module", then the topmost module will be added as main when the runtime is linked to the target vm.

This is the default behavior.

As some runtime may be used to link sub-components which are not meant to build a complete application, this method is provided to inhibit this behavior.

Parameters:

b

true if this runtime will provide the main module to the VM at link time, false otherwise.

bool Falcon::Runtime::hasMainModule ( ) const [inline]

Returns true if this loader top module is the main module for a final application.

By default, this is true unless changed with hasMainModule(bool).

bool Falcon::Runtime::hasPendingModules ( ) const [inline]

Returns true if there are still some pending modules.

This means that the module list may not be completed in case the runtime is not using a loader to resolve dependencies.

void Falcon::Runtime::loadFile	(	const String &	file,
		bool	bIsPrivate = `false`
	)

Loads the given module and adds it to the runtime.

This is actually a just shortcut to load a module from a given file. The name is resolved by the module loader, and if load is succesfull, then the module is added to the runtime.

Parameters:

	file	the file name of the module to be loaded
	bIsPrivate	false (default) to allow the module to export its symbols to the VM, true otherwise.

Exceptions:

Error

on compilation/load error.

void Falcon::Runtime::loadName	(	const String &	name,
		const String &	parent = `""`,
		bool	bIsPrivate = `false`
	)

Loads the given module and adds it to the runtime.

This is actually a just shortcut to load a module with a given logical name. The name is resolved by the module loader, and if load is succesfull, then the module is added to the runtime.

Parameters:

	name	the logical name of the module to be loaded
	parent	the logical name of the parent module, if any
	bIsPrivate	false (default) to allow the module to export its symbols to the VM, true otherwise.

Exceptions:

Error

on compilation/load error.

const ModuleMap* Falcon::Runtime::moduleMap ( ) const [inline]

Return the symbol tably containing the global symbols.

As a symbol table is just a symbol map that self-deletes owned symbol, and as this map just holds a reference to some symbols inside the modules contained in the runtime, the map must not destroy the symbols at runtime destruction. Symbols are owned by symbols table, which are owned by their modules. However, as modules cannot be deleted while they are still owned by some Runtime, this references are guaranteed to stay valid at least untill this Runtime is destroyed. Return the modules linked in this runtime.

const ModuleVector* Falcon::Runtime::moduleVector ( ) const [inline]

Return the modules linked in this runtime.

uint32 Falcon::Runtime::size ( ) [inline]

Return the amount of modules in this runtime.

bool Falcon::Runtime::willLoad ( ) [inline]

Tell wether this runtime tries to interpret the module load requests or just denies them.

Returns:: true if the runtime fulfills module requests with a provided ModuleLoader, false otherwise.

The documentation for this class was generated from the following file:

/home/gian/Progetti/falcon/core/include/falcon/runtime.h


Public Member Functions
void	addModule (Module *mod, bool bIsPrivate=false)
	Adds a module to the Runtime library.
Module *	findModule (const String &name)
	Returns a module with the given name.
Module *	findModuleByID (uint32 id)
	Return the nth module.
void	hasMainModule (bool b)
	Changes the relevance of this runtime.
bool	hasMainModule () const
	Returns true if this loader top module is the main module for a final application.
bool	hasPendingModules () const
	Returns true if there are still some pending modules.
void	loadFile (const String &file, bool bIsPrivate=false)
	Loads the given module and adds it to the runtime.
void	loadName (const String &name, const String &parent="", bool bIsPrivate=false)
	Loads the given module and adds it to the runtime.
const ModuleMap *	moduleMap () const
	Return the symbol tably containing the global symbols.
const ModuleVector *	moduleVector () const
	Return the modules linked in this runtime.
	Runtime ()
	Creates the runtime.
	Runtime (ModuleLoader loader, VMachine provider=0)
	Creates the runtime and allows module load requests.
uint32	size ()
	Return the amount of modules in this runtime.
bool	willLoad ()
	Tell wether this runtime tries to interpret the module load requests or just denies them.
	~Runtime ()
	Destroy this Runtime.