Doomsday SDK  2.3
Core engine library and supporting libraries
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
de::Process Class Reference

Executes a script. More...

#include <process.h>

Classes

class  HangError
 Execution is taking too long to complete. More...
 
class  NotStoppedError
 The process is running while an operation is attempted that requires the process to be stopped. More...
 
class  SuspendError
 Suspending or resuming fails. More...
 

Public Types

enum  CallResult { IgnoreResult, TakeResult }
 
using Namespaces = Evaluator::Namespaces
 
enum  State { Running, Suspended, Stopped }
 A process is always in one of these states. More...
 

Public Member Functions

 Process (Record *externalGlobalNamespace=0)
 Constructs a new process. More...
 
 Process (Script const &script)
 Constructs a new process. More...
 
void call (Function const &function, ArrayValue const &arguments, Value *self=0)
 Performs a function call. More...
 
void clear ()
 Resets the process to an empty state. More...
 
Contextcontext (duint downDepth=0)
 Return an execution context. More...
 
dsize depth () const
 Determines the current depth of the call stack. More...
 
void execute ()
 Execute the next command(s) in the script. More...
 
void finish (Value *returnValue=0)
 Finish the execution of the topmost context. More...
 
Recordglobals ()
 Returns the global namespace of the process. More...
 
Recordlocals ()
 Returns the local namespace of the process. More...
 
void namespaces (Namespaces &spaces) const
 Collects the namespaces currently visible. More...
 
ContextpopContext ()
 Pops the topmost context off the stack and returns it. More...
 
void pushContext (Context *context)
 Pushes a new context to the process's stack. More...
 
void run (Script const &script)
 Starts running the given script. More...
 
void setWorkingPath (String const &newWorkingPath)
 Changes the working path of the process. More...
 
State state () const
 
void stop ()
 Stops the execution of the script. More...
 
void suspend (bool suspended=true)
 Suspends or resumes execution of the script. More...
 
String const & workingPath () const
 Returns the current working path. More...
 

Static Public Member Functions

template<typename... Args>
static ValuescriptCall (CallResult result, Record &globals, String const &function, Args... args)
 Calls a script function. More...
 
template<typename ReturnValueType , typename... Args>
static ReturnValueType * scriptCall (Record &globals, String const &function, Args... args)
 

Detailed Description

Executes a script.

The process maintains the execution environment, including things like local variables and keeping track of which statement is being executed.

Definition at line 155 of file process.h.

Member Typedef Documentation

◆ Namespaces

Definition at line 179 of file process.h.

Member Enumeration Documentation

◆ CallResult

Enumerator
IgnoreResult 
TakeResult 

Definition at line 330 of file process.h.

◆ State

A process is always in one of these states.

Enumerator
Running 

The process is running normally.

Suspended 

The process has been suspended and will not continue running until restored.

A process cannot restore itself from a suspended state.

Stopped 

The process has reached the end of the script or has been terminated.

Definition at line 169 of file process.h.

Constructor & Destructor Documentation

◆ Process() [1/2]

de::Process::Process ( Record externalGlobalNamespace = 0)

Constructs a new process.

The process is initialized to STOPPED state.

Parameters
externalGlobalNamespaceNamespace to use as the global namespace of the process. If not specified, a private global namespace is created for the process. The process does not get ownership of the external global namespace.

Definition at line 150 of file process.cpp.

◆ Process() [2/2]

de::Process::Process ( Script const &  script)

Constructs a new process.

The process is initialized to RUNNING state.

Parameters
scriptScript to run. No reference to the script is retained apart from pointing to its statements. The script instance must remain in existence while the process is running, as it is the owner of the statements.

Definition at line 158 of file process.cpp.

Member Function Documentation

◆ call()

void de::Process::call ( Function const &  function,
ArrayValue const &  arguments,
Value self = 0 
)

Performs a function call.

A new context is created on the context stack and the function's statements are executed on the new stack. After the call is finished, the result value is pushed to the calling context's evaluator.

Parameters
functionFunction to call.
argumentsArguments for the function. The array's first element must be a DictionaryValue containing values for the named arguments of the call. The rest of the array are the unnamed arguments.
selfOptional scope that becomes the value of the "self" variable. Ownership given to Process.

Definition at line 351 of file process.cpp.

◆ clear()

void de::Process::clear ( )

Resets the process to an empty state.

All existing content in the process's context stack is removed, leaving the process in a similar state than after construction.

Definition at line 171 of file process.cpp.

◆ context()

Context & de::Process::context ( duint  downDepth = 0)

Return an execution context.

By default returns the topmost context.

Parameters
downDepthHow many levels to go down. There are depth() levels in the context stack.
Returns
Context at downDepth.

Definition at line 285 of file process.cpp.

◆ depth()

dsize de::Process::depth ( ) const

Determines the current depth of the call stack.

Definition at line 176 of file process.cpp.

◆ execute()

void de::Process::execute ( )

Execute the next command(s) in the script.

Execution continues until the script leaves RUNNING state.

Exceptions
HangErrorExecution takes too long.

Definition at line 222 of file process.cpp.

◆ finish()

void de::Process::finish ( Value returnValue = 0)

Finish the execution of the topmost context.

Execution will continue from the second topmost context.

Parameters
returnValueValue to use as the return value from the context. Takes ownership of the value.

Definition at line 310 of file process.cpp.

◆ globals()

Record & de::Process::globals ( )

Returns the global namespace of the process.

This is always the bottommost context in the stack.

Definition at line 436 of file process.cpp.

◆ locals()

Record & de::Process::locals ( )

Returns the local namespace of the process.

This is always the topmost context in the stack.

Definition at line 450 of file process.cpp.

◆ namespaces()

void de::Process::namespaces ( Namespaces spaces) const

Collects the namespaces currently visible.

This includes the process's own stack and the global namespaces.

Parameters
spacesThe namespaces are collected here. The order is important: earlier namespaces shadow the subsequent ones.

Definition at line 411 of file process.cpp.

◆ popContext()

Context * de::Process::popContext ( )

Pops the topmost context off the stack and returns it.

Ownership given to caller.

Definition at line 295 of file process.cpp.

◆ pushContext()

void de::Process::pushContext ( Context context)

Pushes a new context to the process's stack.

Parameters
contextContext. Ownership taken.

Definition at line 290 of file process.cpp.

◆ run()

void de::Process::run ( Script const &  script)

Starts running the given script.

Note that the process must be in the FINISHED state for this to be a valid operation.

Parameters
scriptScript to run. No reference to the script is retained apart from pointing to its statements. The script instance must remain in existence while the process is running, as it is the owner of the statements.

Definition at line 181 of file process.cpp.

◆ scriptCall() [1/2]

template<typename... Args>
static Value* de::Process::scriptCall ( CallResult  result,
Record globals,
String const &  function,
Args...  args 
)
inlinestatic

Calls a script function.

Native arguments are converted to script source text and then parsed into Values when the call is executed.

Only non-named function arguments are supported by this method.

The namespace global may be modified if some of the argument values require variables, e.g., for refering Records. The created variables are named __argN__, with N being an increasing number.

Parameters
resultWhat to do with the result value.
globalsGlobal namespace where to execute the call.
functionName of the function.
argsArgument values for the function call.
Returns
Depending on result, returns nullptr or the return value from the call. Caller gets ownership of the possibly returned Value.

Definition at line 351 of file process.h.

◆ scriptCall() [2/2]

template<typename ReturnValueType , typename... Args>
static ReturnValueType* de::Process::scriptCall ( Record globals,
String const &  function,
Args...  args 
)
inlinestatic

Definition at line 366 of file process.h.

◆ setWorkingPath()

void de::Process::setWorkingPath ( String const &  newWorkingPath)

Changes the working path of the process.

File system access within the process is relative to the working path.

Parameters
newWorkingPathNew working path for the process.

Definition at line 346 of file process.cpp.

◆ state()

Process::State de::Process::state ( ) const

Definition at line 166 of file process.cpp.

◆ stop()

void de::Process::stop ( )

Stops the execution of the script.

The process is set to the FINISHED state, which means it must be rerun with a new script.

Definition at line 200 of file process.cpp.

◆ suspend()

void de::Process::suspend ( bool  suspended = true)

Suspends or resumes execution of the script.

Definition at line 189 of file process.cpp.

◆ workingPath()

String const & de::Process::workingPath ( ) const

Returns the current working path.

Definition at line 341 of file process.cpp.


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