phasor.Runtime Namespace Reference

Functions
bytes	_to_bytes ("Union[bytes, bytearray, Bytecode]" bytecode)
	_get_lib ()
bytes	_cwd_bytes ()
	_ptr (Optional[StateHandle] state)
	_build_argv (Sequence[str] args)
Bytecode	_two_pass_compile (compile_fn, *bytes leading_args)
StateHandle	new_state ()
None	init_stdlib (StateHandle state)
None	free_state (StateHandle state)
None	reset_state (StateHandle state, *, bool reset_functions=False, bool reset_variables=False)
bytes	compile_phs (str script, *, str module_name=_DEFAULT_MODULE_NAME, Optional[str] module_path=None)
bytes	compile_phs_file (str|Path path, *, Optional[str] module_name=None, Optional[str] module_path=None)
bytes	compile_pul (str script, *, str module_name=_DEFAULT_MODULE_NAME)
bytes	compile_pul_file (str|Path path, *, Optional[str] module_name=None)
int	run (Union[bytes, bytearray, Bytecode] bytecode, *, Optional[StateHandle] state=None, str module_name=_DEFAULT_MODULE_NAME, Sequence[str] args=())
int	run_file (str|Path path, *, Optional[StateHandle] state=None, Optional[str] module_name=None, Sequence[str] args=())
int	evaluate_phs (str script, *, Optional[StateHandle] state=None, str module_name=_DEFAULT_MODULE_NAME, Optional[str] module_path=None, bool verbose=False)
int	evaluate_phs_file (str|Path path, *, Optional[StateHandle] state=None, Optional[str] module_name=None, bool verbose=False)
int	evaluate_pul (str script, *, Optional[StateHandle] state=None, str module_name=_DEFAULT_MODULE_NAME)
int	evaluate_pul_file (str|Path path, *, Optional[StateHandle] state=None, Optional[str] module_name=None)

Variables
	_ffi = FFI()
dict	_CANDIDATES
dict	_LOAD_HINT
	_lib = None
str	_DEFAULT_MODULE_NAME = "Python"
	StateHandle = object

Detailed Description

phasor.Runtime
==============
cffi bindings for the PhasorRT shared library.

State is an opaque handle returned by :func:`new_state` and passed into
execution and evaluation functions.  This mirrors the C API directly

Function Documentation

_build_argv()

phasor.Runtime._build_argv ( Sequence[str] args )

protected

Convert a sequence of strings to ``(argc, argv_p)`` for cffi.

Definition at line 106 of file Runtime.py.

Here is the caller graph for this function:

_cwd_bytes()

bytes phasor.Runtime._cwd_bytes ( )

protected

Definition at line 97 of file Runtime.py.

Here is the caller graph for this function:

_get_lib()

phasor.Runtime._get_lib ( )

protected

Definition at line 70 of file Runtime.py.

Here is the caller graph for this function:

_ptr()

phasor.Runtime._ptr ( Optional[StateHandle] state )

protected

Return the raw cffi pointer for *state*, or NULL if *state* is None.

Definition at line 101 of file Runtime.py.

Here is the caller graph for this function:

_to_bytes()

bytes phasor.Runtime._to_bytes ( "Union[bytes, bytearray, Bytecode]" bytecode )

protected

Accept raw bytes/bytearray *or* a Bytecode object; always return bytes.

Definition at line 21 of file Runtime.py.

Here is the caller graph for this function:

_two_pass_compile()

Bytecode phasor.Runtime._two_pass_compile ( compile_fn, *bytes leading_args )

protected

Size-probe then compile as required by the C API.

Returns:
    A :class:`~phasor.Bytecode.Bytecode` object built from the compiled output.

Definition at line 114 of file Runtime.py.

Here is the caller graph for this function:

compile_phs()

bytes phasor.Runtime.compile_phs	(	str	script,
		*	,
		str	module_name = _DEFAULT_MODULE_NAME,
		Optional[str]	module_path = None )

Compile a Phasor (``.phs``) source string to ``.phsb`` bytecode.

Args:
    script: Phasor source code to compile.
    module_name: Name reported in error messages. Defaults to ``"Python"``.
    module_path: Directory for resolving compile-time imports.
        Defaults to the current working directory.

Returns:
    A :class:`~phasor.Bytecode.Bytecode` object, ready to inspect, modify,
    pass to :func:`run`, or serialise with
    :meth:`~phasor.Bytecode.Bytecode.save` / :meth:`~phasor.Bytecode.Bytecode.to_bytes`.

Raises:
    RuntimeError: If compilation fails.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 216 of file Runtime.py.

Here is the call graph for this function:

Here is the caller graph for this function:

compile_phs_file()

bytes phasor.Runtime.compile_phs_file	(	str | Path	path,
		*	,
		Optional[str]	module_name = None,
		Optional[str]	module_path = None )

Read a ``.phs`` file and compile it to ``.phsb`` bytecode.

Args:
    path: Path to the ``.phs`` source file.
    module_name: Name reported in error messages.
        Defaults to the file's stem (e.g. ``"hello"`` for ``hello.phs``).
    module_path: Directory for resolving compile-time imports.
        Defaults to the parent directory of *path*.

Returns:
    A :class:`~phasor.Bytecode.Bytecode` object.

Raises:
    FileNotFoundError: If *path* does not exist.
    RuntimeError: If compilation fails.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 248 of file Runtime.py.

Here is the call graph for this function:

compile_pul()

bytes phasor.Runtime.compile_pul	(	str	script,
		*	,
		str	module_name = _DEFAULT_MODULE_NAME )

Compile a Pulsar (``.pul``) source string to ``.phsb`` bytecode.

Args:
    script: Pulsar source code to compile.
    module_name: Name reported in error messages. Defaults to ``"Python"``.

Returns:
    A :class:`~phasor.Bytecode.Bytecode` object.

Raises:
    RuntimeError: If compilation fails.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 281 of file Runtime.py.

Here is the call graph for this function:

Here is the caller graph for this function:

compile_pul_file()

bytes phasor.Runtime.compile_pul_file	(	str | Path	path,
		*	,
		Optional[str]	module_name = None )

Read a ``.pul`` file and compile it to ``.phsb`` bytecode.

Args:
    path: Path to the ``.pul`` source file.
    module_name: Name reported in error messages.
        Defaults to the file's stem.

Returns:
    A :class:`~phasor.Bytecode.Bytecode` object.

Raises:
    FileNotFoundError: If *path* does not exist.
    RuntimeError: If compilation fails.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 306 of file Runtime.py.

Here is the call graph for this function:

evaluate_phs()

int phasor.Runtime.evaluate_phs	(	str	script,
		*	,
		Optional[StateHandle]	state = None,
		str	module_name = _DEFAULT_MODULE_NAME,
		Optional[str]	module_path = None,
		bool	verbose = False )

Compile and execute a Phasor source string.

Args:
    script: Phasor source code.
    state: An optional handle from :func:`new_state`. When ``None``,
        PhasorRT creates and manages a transient state internally.
    module_name: Name reported in error messages. Defaults to ``"Python"``.
    module_path: Directory for resolving compile-time imports.
        Defaults to the current working directory.
    verbose: Print the AST to stdout when ``True``.

Returns:
    The script's exit code.

Raises:
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 401 of file Runtime.py.

Here is the call graph for this function:

Here is the caller graph for this function:

evaluate_phs_file()

int phasor.Runtime.evaluate_phs_file	(	str | Path	path,
		*	,
		Optional[StateHandle]	state = None,
		Optional[str]	module_name = None,
		bool	verbose = False )

Read and evaluate a ``.phs`` source file.

The file's parent directory is automatically used for resolving
compile-time imports.

Args:
    path: Path to the ``.phs`` source file.
    state: An optional handle from :func:`new_state`.
    module_name: Name reported in error messages.
        Defaults to the file's stem.
    verbose: Print the AST to stdout when ``True``.

Returns:
    The script's exit code.

Raises:
    FileNotFoundError: If *path* does not exist.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 436 of file Runtime.py.

Here is the call graph for this function:

evaluate_pul()

int phasor.Runtime.evaluate_pul	(	str	script,
		*	,
		Optional[StateHandle]	state = None,
		str	module_name = _DEFAULT_MODULE_NAME )

Compile and execute a Pulsar source string.

Args:
    script: Pulsar source code.
    state: An optional handle from :func:`new_state`. When ``None``,
        PhasorRT creates and manages a transient state internally.
    module_name: Name reported in error messages. Defaults to ``"Python"``.

Returns:
    The script's exit code.

Raises:
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 474 of file Runtime.py.

Here is the call graph for this function:

Here is the caller graph for this function:

evaluate_pul_file()

int phasor.Runtime.evaluate_pul_file	(	str | Path	path,
		*	,
		Optional[StateHandle]	state = None,
		Optional[str]	module_name = None )

Read and evaluate a ``.pul`` source file.

Args:
    path: Path to the ``.pul`` source file.
    state: An optional handle from :func:`new_state`.
    module_name: Name reported in error messages.
        Defaults to the file's stem.

Returns:
    The script's exit code.

Raises:
    FileNotFoundError: If *path* does not exist.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 501 of file Runtime.py.

Here is the call graph for this function:

free_state()

None phasor.Runtime.free_state

(

StateHandle

state

)

Release a VM state created by :func:`new_state`.

The handle must not be used after this call.

Args:
    state: The handle returned by :func:`new_state`.

Raises:
    RuntimeError: If ``freeState()`` reports failure (double-free or corrupt pointer).
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 172 of file Runtime.py.

Here is the call graph for this function:

init_stdlib()

None phasor.Runtime.init_stdlib

(

StateHandle

state

)

Register standard library functions into a given state.

Args: 
    state: The handle returned by :func:`new_state`.

Raises:
    RuntimeError: If ``initStdLib()`` reports failure.

Definition at line 160 of file Runtime.py.

Here is the call graph for this function:

new_state()

StateHandle phasor.Runtime.new_state

(

)

Allocate a new Phasor VM state and return its opaque handle.

Pass the handle to any execution or evaluation function via the
``state`` parameter to reuse the same VM across multiple calls,
preserving globals and registered functions between them.

Always pair with :func:`free_state` when the state is no longer needed.

Returns:
    An opaque cffi handle representing the new VM state.

Raises:
    RuntimeError: If ``createState()`` returns NULL.
    OSError: If the PhasorRT library cannot be loaded.

Example::

    vm = new_state()
    free_state(vm)

Definition at line 133 of file Runtime.py.

Here is the call graph for this function:

reset_state()

None phasor.Runtime.reset_state	(	StateHandle	state,
		*	,
		bool	reset_functions = False,
		bool	reset_variables = False )

Reset a VM state (stack, PC, and bytecode are always cleared).

Args:
    state: The handle returned by :func:`new_state`.
    reset_functions: Also clear all registered functions when ``True``.
    reset_variables: Also clear all global variables when ``True``.

Raises:
    RuntimeError: If ``resetState()`` reports failure.
    OSError: If the PhasorRT library cannot be loaded.

Example::

    # Soft reset: keep globals and functions, just reset execution state.
    reset_state(vm)

    # Full wipe.
    reset_state(vm, reset_functions=True, reset_variables=True)

Definition at line 188 of file Runtime.py.

Here is the call graph for this function:

run()

int phasor.Runtime.run	(	Union[bytes, bytearray, Bytecode]	bytecode,
		*	,
		Optional[StateHandle]	state = None,
		str	module_name = _DEFAULT_MODULE_NAME,
		Sequence[str]	args = () )

Execute pre-compiled ``.phsb`` bytecode.

Args:
    bytecode: Raw ``.phsb`` bytes **or** a :class:`~phasor.Bytecode.Bytecode`
        object (e.g. from :func:`compile_phs` or
        :meth:`~phasor.Bytecode.Bytecode.load`).
    state: An optional handle from :func:`new_state`. When ``None``,
        PhasorRT creates and manages a transient state internally.
    module_name: Name reported in error messages. Defaults to ``"Python"``.
    args: Command-line arguments forwarded to the script as ``argv``.

Returns:
    The script's exit code (``-1`` may indicate an unhandled VM exception).

Raises:
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 334 of file Runtime.py.

Here is the call graph for this function:

Here is the caller graph for this function:

run_file()

int phasor.Runtime.run_file	(	str | Path	path,
		*	,
		Optional[StateHandle]	state = None,
		Optional[str]	module_name = None,
		Sequence[str]	args = () )

Load a ``.phsb`` file and execute it.

Args:
    path: Path to the ``.phsb`` bytecode file.
    state: An optional handle from :func:`new_state`.
    module_name: Name reported in error messages.
        Defaults to the file's stem.
    args: Command-line arguments forwarded to the script.

Returns:
    The script's exit code.

Raises:
    FileNotFoundError: If *path* does not exist.
    OSError: If the PhasorRT library cannot be loaded.

Definition at line 367 of file Runtime.py.

Here is the call graph for this function:

Variable Documentation

_CANDIDATES

dict phasor.Runtime._CANDIDATES

protected

Initial value:

=  {
    "linux":  ["libphasorrt.so", "libphasorrt.so.1"],
    "darwin": ["libphasorrt.dylib", "libphasorrt.1.dylib"],
    "win32":  ["phasorrt.dll"],
}

Definition at line 55 of file Runtime.py.

_DEFAULT_MODULE_NAME

str phasor.Runtime._DEFAULT_MODULE_NAME = "Python"

protected

Definition at line 92 of file Runtime.py.

_ffi

phasor.Runtime._ffi = FFI()

protected

Definition at line 27 of file Runtime.py.

_lib

phasor.Runtime._lib = None

protected

Definition at line 67 of file Runtime.py.

_LOAD_HINT

dict phasor.Runtime._LOAD_HINT

protected

Initial value:

=  {
    "linux":  "Set LD_LIBRARY_PATH or run ldconfig after installing Phasor.",
    "darwin": "Set DYLD_LIBRARY_PATH or install Phasor.",
    "win32":  "Add phasorrt.dll to your system PATH",
}

Definition at line 61 of file Runtime.py.

StateHandle

phasor.Runtime.StateHandle = object

Definition at line 94 of file Runtime.py.