API¶
Platform Object¶
-
class
v8cffi.platform.
_Platform
[source]¶ V8 platform environment. The underlying platform is a singleton that must only be initialized once per process.
Should be used through
platform
Variables: - natives_path (str) – Path to natives_blob.bin
- snapshot_path (str) – Path to snapshot_blob.bin
-
create_vm
()[source]¶ Create a
VM
for running JS scripts within an isolated environmentReturns: Instance of VM
Return type: VM
-
is_alive
()[source]¶ Check is initialized and was not exited
Returns: Whether the platform is alive or not Return type: bool
-
set_up
()[source]¶ Initialize the V8 platform. Remember to call
tear_down()
before exiting the application. It’s recommended to use awith
statement instead of this method to ensure clean up.This must only be called once in an application lifetime
Raises: V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
-
v8cffi.platform.
platform
– Platform object (singleton)¶ V8 platform environment. The underlying platform is a singleton that must only be initialized once per process.
Should be used through
platform
Variables: - natives_path (str) – Path to natives_blob.bin
- snapshot_path (str) – Path to snapshot_blob.bin
VM Object¶
-
class
v8cffi.vm.
VM
(platform)[source]¶ Holds the VM state (V8 isolate). Running scripts within a VM is thread-safe, but only a single thread will execute code at a given time (there is a Global Lock). It’s feasible to run one VM per thread or to have a pre-initialized pool.
There may be many VMs per platform
Parameters: platform ( _Platform
) – Initialized platform-
create_context
()[source]¶ Create a
Context
for running JS scriptsReturns: Instance of Context
Return type: Context
-
is_alive
()[source]¶ Check the vm is initialized and was not exited
Returns: Whether the vm is alive or not Return type: bool
-
set_up
()[source]¶ Initialize the VM. Remember to call
tear_down()
before exiting the application. It’s recommended to use awith
statement instead of this method to ensure clean upRaises: V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
-
Context Object¶
-
class
v8cffi.context.
Context
(vm)[source]¶ An execution environment that allows separate, unrelated, JS applications to run in a single instance of V8. It may be thought as a browser tab.
Running scripts within the same Context is thread-safe.
There may be many Contexts per VM
Parameters: vm ( VM
) – Initialized VM-
load_libs
(scripts_paths)[source]¶ Load script files into the context. This can be thought as the HTML script tag. The files content must be utf-8 encoded.
This is a shortcut for reading the files and pass the content to
run_script()
Parameters: scripts_paths (list) – Script file paths.
Raises: - OSError – If there was an error manipulating the files. This should not normally be caught
- V8Error – if there was an error running the JS script
-
run_script
(script, identifier='<anonymous>')[source]¶ Run a JS script within the context. All code is ran synchronously, there is no event loop. It’s thread-safe
Parameters: - script (bytes or str) – utf-8 encoded or unicode string
- identifier (bytes or str) – utf-8 encoded or unicode string. This is used as the name of the script (ie: in stack-traces)
Returns: Result of running the JS script
Return type: str
Raises: V8Error – if there was an error running the JS script
-
set_up
()[source]¶ Initialize the context. Remember to call
tear_down()
before exiting the application. It’s recommended to use awith
statement instead of this method to ensure clean upRaises: V8MemoryError – if there is no memory for allocating it, the process should die afterwards anyway, there is little point in catching this
-