ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
alib::expressions::Scope Struct Reference

Description:

This type is used as the default class to provide access to program data when evaluating ALib expressions. Usually a derived type which contains references to necessary application data is passed to the method ExpressionVal::Evaluate. Then, custom callback functions may cast instances of this type that they receive back to the derived type and access such application-specific data.

Also, scope objects are used to store intermediate results as well as the final one, in the case that such results are not of a simple type that can be boxed Box "by value".

For this, two different allocator objects are provided. One for compile-time results and one for those needed at evaluation-time.

A scope object can be reused for evaluating the same expression several times. Before the evaluation, the custom "scoped data" has to be set. With each reuse, the method Reset will be invoked internally. Hence, if custom storage members are added in derived types, this method has to be overwritten to a) invoke the original method and b) clean such custom types.

One singleton of this type, which is used to store compile-time data, is created with the virtual method Compiler::createCompileTimeScope. If compile-time invokable custom callback methods use custom storage allocators, this method has to be overridden to return the proper custom version of this class. (Note, this is not needed for the evaluation-time instances, as this is created in the custom code unit anyhow and passed to method ExpressionVal::Evaluate).

See also
  • For details on the use of scopes see the manual chapter 8 Scopes.
  • This is an almost completely public struct. The design rationale behind this is explained in the manual chapter 3.4 Bauhaus Code Style

Definition at line 65 of file scope.inl.

Inheritance diagram for alib::expressions::Scope:
[legend]
Collaboration diagram for alib::expressions::Scope:
[legend]

Inner Type Index:

struct  VMMembers
 Members used by the virtual machine. This is constructed only with evaluation-time scopes. More...
 

Public Field Index:

MonoAllocatorAllocator
 
lang::DbgCriticalSections DCS
 
MonoAllocatorEvalScopeAllocator
 
VMMembersEvalScopeVMMembers
 The members used for the virtual machine. Available only with evaluation-time instances.
 
SPFormatter Formatter
 
HashMap< MonoAllocator, NString, ScopeResource * > * NamedResources
 
StdVectorMono< Box > * Stack
 

Public Method Index:

 Scope (const Scope &)=delete
 Deleted copy constructor.
 
ALIB_DLL Scope (MonoAllocator &allocator, SPFormatter &formatter)
 
ALIB_DLL Scope (SPFormatter &formatter)
 
virtual ALIB_DLL ~Scope ()
 Virtual destructor.
 
bool IsCompileTime ()
 
void operator= (const Scope &)=delete
 Deleted copy assignment.
 
virtual ALIB_DLL void Reset ()
 

Protected Method Index:

virtual ALIB_DLL void freeResources ()
 This method is called in the destructor, as well as in method Reset.
 

Field Details:

◆ Allocator

MonoAllocator& alib::expressions::Scope::Allocator

Monotonic allocator used to store temporary data and results. The allocated data within this object becomes cleared automatically by method Reset, at the moment an expression is evaluated the next time (usually with different custom scope data).

Note that this allocator is not cleared for the compile-time scope instance.

Definition at line 101 of file scope.inl.

◆ DCS

lang::DbgCriticalSections alib::expressions::Scope::DCS

Debug-tool to detect usage of evaluation scope from within multiple threads (which is not allowed). It is set by the virtual machine when running programs.

Definition at line 134 of file scope.inl.

◆ EvalScopeAllocator

MonoAllocator* alib::expressions::Scope::EvalScopeAllocator

Evaluation-scope allocator. With compile-time scopes, this is allocator will not be initialized.

Definition at line 93 of file scope.inl.

◆ EvalScopeVMMembers

VMMembers* alib::expressions::Scope::EvalScopeVMMembers

The members used for the virtual machine. Available only with evaluation-time instances.

Definition at line 129 of file scope.inl.

◆ Formatter

SPFormatter alib::expressions::Scope::Formatter

Used to convert numbers to strings and vice versa. In addition, expression function Format of built-in compiler plugin Strings uses this object to perform the formatting of arbitrary objects according to a given format string.

Hence, to support customized format strings, a different formatter is to be passed here. Default format string conventions provided with ALib are python style and java/printf-like style.

The default implementation of method Compiler::createCompileTimeScope provides the field Compiler::CfgFormatter with the constructor of the default compile-time scope.

Definition at line 120 of file scope.inl.

◆ NamedResources

HashMap<MonoAllocator, NString, ScopeResource*>* alib::expressions::Scope::NamedResources

A list of user-defined, named resources. Named resources may be allocated at compile-time and used at evaluation-time.
This pointer is only set with compile-time scopes.

Definition at line 126 of file scope.inl.

◆ Stack

StdVectorMono<Box>* alib::expressions::Scope::Stack

This is the argument stack used by class detail::VirtualMachine when evaluating expressions.
With compilation, it used to "simulate" evaluation calls at compile-time.

Definition at line 106 of file scope.inl.

Constructor(s) / Destructor Details:

◆ Scope() [1/2]

alib::expressions::Scope::Scope ( SPFormatter & formatter)

Constructor used with evaluation scopes. Creates a mono allocator.
Usually, for parameter formatter field Compiler::CfgFormatter should be provided.

Parameters
formatterA reference to a std::shared_ptr holding a formatter. Usually Compiler::CfgFormatter.

Definition at line 39 of file compiler.cpp.

◆ Scope() [2/2]

alib::expressions::Scope::Scope ( MonoAllocator & allocator,
SPFormatter & formatter )

Constructor used with compile-time scopes. Receives the allocator from the expression instance.
Usually, for parameter formatter field Compiler::CfgFormatter should be provided.

Parameters
allocatorThe allocator of the expression.
formatterA reference to a std::shared_ptr holding a formatter. Usually Compiler::CfgFormatter.

Definition at line 51 of file compiler.cpp.

◆ ~Scope()

alib::expressions::Scope::~Scope ( )
virtual

Virtual destructor.

Definition at line 65 of file compiler.cpp.

Here is the call graph for this function:

Method Details:

◆ freeResources()

void alib::expressions::Scope::freeResources ( )
protectedvirtual

This method is called in the destructor, as well as in method Reset.

Definition at line 78 of file compiler.cpp.

Here is the call graph for this function:

◆ IsCompileTime()

bool alib::expressions::Scope::IsCompileTime ( )
inline

Usually, this method is unnecessary to be checked. It is useful and provided to support more complicated management of resources, i.e. allocation of resources at compile-time which are later used for evaluation.

Returns
true if this is a compile-time invocation, false otherwise.

Definition at line 169 of file scope.inl.

◆ Reset()

void alib::expressions::Scope::Reset ( )
virtual

Scope objects usually are reused, either for evaluating the same expression using different scoped data (attached to derived versions of this class), or for evaluating different expression.
Such a reuse is internally detected, and if so, this method is invoked.

Instances of this class used as compilation scope, are not reset during the life-cycle of an expression.

Derived versions of this class need to free allocations performed by callback functions.

Definition at line 87 of file compiler.cpp.

Here is the call graph for this function:

The documentation for this struct was generated from the following files: