Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

Functions

CurrentTime()

Returns the current system local time as a TimeStamp instance.

CurrentTime( )
Returns:

A new TimeStamp instance.

Returns the current system local time as a TimeStamp instance. The function can never fail.

PageDict()

Creates a paged dictionary (which is internally represented as a B-Tree).

PageDict( pageSize )
pageSize

size of pages expressed in maximum items.

Returns:

A new dictionary.

The function returns a Falcon dictionary that can be handled exactly as a normal dictionary. The difference is only in the internal management of memory allocation and tree balance. Default Falcon dictionaries (the ones created with the “[=>]” operator) are internally represented as paired linear vectors of ordered entries. They are extremely efficient to store a relatively small set of data, whose size, and possibly key order, is known in advance. As this is exactly the condition under which source level dictionary are created, this way to store dictionary is the default in Falcon. The drawback is that if the data grows beyond a critical mass linear dictionary may become sluggishly slow and hang down the whole VM processing.

This function, which is actually a class factory function (this is the reason why its name begins in uppercase), returns an empty Falcon dictionary that is internally organized as a B-Tree structure. At a marginal cost in term of memory with respect to the mere storage of falcon items, which is used as spare and growth area, this structure offer high performances on medium to large amount of data to be ordered and searched. Empirical tests in Falcon language showed that this structure can scale up easily to several millions items.

In general, if a Falcon dictionary is meant to store large data, above five to ten thousands elements, or if the size of stored data is not known in advance, using this structure instead of the default Falcon dictionaries is highly advisable.

ParseRFC2822()

Parses a RFC2822 formatted date and returns a timestamp instance.

ParseRFC2822( )
Returns:

A valid TimeStamp instance or nil if the format is invalid.

See also TimeStamp.fromRFC2822.

beginCritical()

Signals the VM that this coroutine must not be interrupted.

beginCritical( )

After this call the VM will abstain from swapping this coroutine out of the execution context. The coroutine can then alter a set of data that must be prepare and readied for other coroutines, and then call endCritical or yield to pass the control back to the other coroutines.

This function is not recursive. Successive calls to beginCritical are not counted, and have actually no effect. The first call to yield will swap out the coroutine, and the first call to endCritical will signal the availability of the routine to be swapped out, no matter how many times beginCritical has been called.

endCritical()

Signals the VM that this coroutine can be interrupted.

endCritical( )

After this call, the coroutine may be swapped. This will happen only if/when the timeslice for this coroutine is over.

This function is not recursive. Successive calls to beginCritical are not counted, and have actually no effect. The first call to yield will swap out the coroutine, and the first call to endCritical will signal the availability of the routine to be swapped out, no matter how many times beginCritical has been called.

exit()

Requires immediate termination of the program.

exit( value )
value

an item representing VM exit code.

The VM execution will be interrupted, with normal state, and the item will be passed in the A register of the VM, where embedding application expects to receive the exit value. Semantic of the exit value will vary depending on the embedding application. The Falcon command line tools (and so, stand alone scripts) will pass this return value to the system if it is an integer, else they will terminate passing 0 to the system.

This function terminates the VM also when there are more coroutines running.

include()

Dynamically loads a module as a plugin.

include( file, [inputEnc], [path], [symDict] )
file

The relative filename of the module.

inputEnc

Input encoding.

path

A string of ';' separated search paths.

symDict

Symbols to be queried (or nil).

Raises:
IOError

if the module cannot be found or load.

A module indicated by filename is compiled, loaded and linked in the running Virtual Machine. The inclusion is relative to the current path, be it set in the script, in the current embedding application or in the falcon command line interpreter. It is possible to use a path relative to the current script path by using the scriptPath variable.

If a dictionary of symbol to be queried is not provided, the module is loaded and its main code, if present, is executed.

If symDict is provided, its keys are strings which refer to symbol names to be searched in the loaded module. If present, the entry are filled with symbols coming from the loaded module. When symDict is provided, the linked module won't have its main code executed (it is possible to execute it at a later time adding "__main__" to the searched symbols). If a symbol is not found, its entry in the dictionary will be set to nil. When loaded this way, the export requests in the loaded module are not honored (import/from semantic).

The compiler Feather module provides a more complete interface to dynamic load and compilation, but this minimal dynamic load support is provided at base level for flexibility.

sleep()

Put the current coroutine at sleep for some time.

sleep( time )
time

Time, in seconds and fractions, that the coroutine wishes to sleep.

Returns:

an item posted by the embedding application.

Raises:
InterruptedError

in case of asynchronous interruption.

This function declares that the current coroutines is not willing to proceed at least for the given time. The VM will swap out the coroutine until the time has elapsed, and will make it eligible to run again after the given time lapse.

The parameter may be a floating point number if a pause shorter than a second is required.

The sleep() function can be called also when the VM has not started any coroutine; this will make it to be idle for the required time.

In embedding applications, the Virtual Machine can be instructed to detect needed idle time and return to the calling application instead of performing a system request to sleep. In this way, embedding applications can use the idle time of the virtual machine to perform background operations. Single threaded applications may continue their execution and schedule continuation of the Virtual Machine at a later time, and multi-threaded applications can perform background message processing.

This function complies with the interrupt protocol. The Virtual Machine may be asynchronously interrupted from the outside (i.e. from another thread). In this case, sleep will immediately raise an InterruptedError instance. The script may just ignore this exception and let the VM to terminate immediately, or it may honor the request after a cleanup it provides in a catch block, or it may simply ignore the request and continue the execution by discarding the error through an appropriate catch block.

See also interrupt_protocol.

suspend()

Temporarily suspends the execution of the Virtual Machine.

suspend( [timeout] )
timeout

Optional maximum wait in seconds.

Returns:

an item posted by the embedding application.

This function is meant to provide a very simple means of communication with the embedding application. Other means are provided as well; they all require less work on the script side, but more integration work on the embedding application side. So, this communcation mean may be interesting for very simple embedding applications, or in the early stage of the integration process.

This function hasn't any utility for stand-alone applications, and should not be used by them, except than for testing.

After this call, the VM exits immediately and the control is given back to the embedder. The embedder can check for the VM to have exited because of a suspend call, and in this case, it may call the VM method Falcon::VMachine::resume() to make the script to proceed from the point it was suspended.

The resume method of the virtual machine may accept an item that is then passed to the suspended script as the return value of the suspend call. In this way, the script may receive a callback notification of events happening in the main application, and manage them. This is an example:

    lastEvent = “none”
 
    while lastEvent != “quit”
 
       lastEvent = suspend()
 
       switch lastEvent
          case “this”
             doThis()
          case “that”
             doThat()
       end
    end

The kind of item that is returned by suspend() call is a convention between the script and the embedding application, and may be a complex item as well as an instance of an embedder specific class.

While in suspended state, the VM may be also destroyed, or the calling module may be unlinked from it, or the execution may be restarted instead of resumed.

yield()

gives up the rest of the coroutine time slice.

yield( )

This signals the VM that the current coroutine is temporarily done, and that another coroutine may be executed. If no other coroutines can be executed, current coroutine is resumed immediately (actually, it is never swapped out).

yieldOut()

Terminates current coroutine.

yieldOut( retval )
retval

a return value for the coroutine.

The current coroutine is terminated. If this is the last coroutine, the VM exits. Calling this function has the same effect of the END virtual machine PCODE.

In multithreading context, exiting from the last coroutine causes a clean termination of the current thread.

See also exit.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0