Task

Typedefs
typedef struct uv_loop_s	uv_loop_t
typedef int	taskid_t
typedef int	promiseid_t
typedef int	exportid_t
typedef struct _tf_taskstub_t	tf_taskstub_t
typedef struct _tf_task_t	tf_task_t
typedef struct _tf_trace_t	tf_trace_t
typedef struct _tf_ssb_t	tf_ssb_t
typedef enum _tf_task_message_t	tf_task_message_t
typedef void()	tf_android_start_service_t(int pipe_fd)
typedef void()	tf_android_stop_service_t()

Enumerations
enum	_tf_task_message_t {   kResolvePromise , kRejectPromise , kInvokeExport , kReleaseExport ,   kReleaseImport , kActivate , kExecute , kKill ,   kSetImports , kGetExports , kLoadFile , kTaskError ,   kTaskTrace , kPrint }

Functions
tf_task_t *	tf_task_create ()
void	tf_task_configure_from_fd (tf_task_t *task, int fd)
void	tf_task_set_ssb_network_key (tf_task_t *task, const char *network_key)
void	tf_task_set_db_path (tf_task_t *task, const char *path)
void	tf_task_set_zip_path (tf_task_t *task, const char *path)
void	tf_task_set_root_path (tf_task_t *task, const char *path)
const char *	tf_task_get_zip_path (tf_task_t *task)
const char *	tf_task_get_root_path (tf_task_t *task)
const char *	tf_task_get_path_with_root (tf_task_t *task, const char *path)
void	tf_task_set_args (tf_task_t *task, const char *args)
bool	tf_task_get_one_proc (tf_task_t *task)
void	tf_task_set_one_proc (tf_task_t *task, bool one_proc)
void	tf_task_activate (tf_task_t *task)
void	tf_task_run (tf_task_t *task)
int	tf_task_execute (tf_task_t *task, const char *file)
void	tf_task_set_trusted (tf_task_t *task, bool trusted)
JSContext *	tf_task_get_context (tf_task_t *task)
void	tf_task_destroy (tf_task_t *task)
exportid_t	tf_task_export_function (tf_task_t *task, tf_taskstub_t *to, JSValue function)
JSValue	tf_task_add_import (tf_task_t *task, taskid_t stub_id, exportid_t export_id)
uv_loop_t *	tf_task_get_loop (tf_task_t *task)
tf_task_t *	tf_task_get (JSContext *context)
tf_trace_t *	tf_task_get_trace (tf_task_t *task)
tf_ssb_t *	tf_task_get_ssb (tf_task_t *task)
const char *	tf_task_get_name (tf_task_t *task)
void	tf_task_print (tf_task_t *task, int argc, JSValueConst *argv)
JSValue	tf_task_allocate_promise (tf_task_t *task, promiseid_t *out_promise)
void	tf_task_reject_promise (tf_task_t *task, promiseid_t promise, JSValue error)
void	tf_task_resolve_promise (tf_task_t *task, promiseid_t promise, JSValue result)
void	tf_task_send_promise_message (tf_task_t *from, tf_taskstub_t *to, tf_task_message_t type, promiseid_t promise, JSValue payload)
void	tf_task_on_receive_packet (int packetType, const char *begin, size_t length, void *userData)
taskid_t	tf_task_allocate_task_id (tf_task_t *task, tf_taskstub_t *stub)
void	tf_task_remove_child (tf_task_t *task, tf_taskstub_t *child)
bool	tf_task_send_error_to_parent (tf_task_t *task, JSValue error)
char *	tf_task_get_debug (tf_task_t *task)
void	tf_task_set_android_service_callbacks (tf_android_start_service_t *start_service, tf_android_stop_service_t *stop_service)
tf_android_start_service_t *	tf_task_get_android_start_service ()
tf_android_stop_service_t *	tf_task_get_android_stop_service ()
void	tf_task_check_jobs (tf_task_t *task)
bool	tf_task_is_shutting_down (tf_task_t *task)
void	tf_task_visit_children (tf_task_t *task, void(*callback)(tf_task_t *task, tf_taskstub_t *stub, void *user_data), void *user_data)
tf_taskstub_t *	tf_task_get_stub (tf_task_t *task, taskid_t id)

Detailed Description

Task is responsible for running JS in C. It exposes just what is needed for sandboxed or trusted code, helps with communiciation between parent and child processes, including function calls and async operations across the boundaries.

Typedef Documentation

exportid_t

typedef int exportid_t

An exported function identifier.

promiseid_t

typedef int promiseid_t

A promise identifier.

taskid_t

typedef int taskid_t

A task identifier.

tf_android_start_service_t

typedef void() tf_android_start_service_t(int pipe_fd)

A callback used to start an Android service.

Parameters

pipe_fd

A file descriptor with which to communicate with the invoking task.

tf_android_stop_service_t

typedef void() tf_android_stop_service_t()

A callback used to stop an Android service.

tf_ssb_t

typedef struct _tf_ssb_t tf_ssb_t

An SSB instance.

tf_task_message_t

typedef enum _tf_task_message_t tf_task_message_t

A message type that can be sent between tasks.

tf_task_t

typedef struct _tf_task_t tf_task_t

A task.

tf_taskstub_t

typedef struct _tf_taskstub_t tf_taskstub_t

A handle to a task.

tf_trace_t

typedef struct _tf_trace_t tf_trace_t

A trace instance.

uv_loop_t

typedef struct uv_loop_s uv_loop_t

An event loop.

Enumeration Type Documentation

_tf_task_message_t

enum _tf_task_message_t

A message type that can be sent between tasks.

Function Documentation

tf_task_activate()

void tf_task_activate

(

tf_task_t *

task

)

Start a task running its script.

Parameters

task

The task.

tf_task_add_import()

JSValue tf_task_add_import	(	tf_task_t *	task,
		taskid_t	stub_id,
		exportid_t	export_id
	)

Create a function that can be called from a handle to an exported function from another task.

Parameters

task	The running task.
stub_id	The task stub from which the function was exported.
export_id	The handle to the function.

Returns

A function that, when called, invokes the corresponding function in the remote task.

tf_task_allocate_promise()

JSValue tf_task_allocate_promise	(	tf_task_t *	task,
		promiseid_t *	out_promise
	)

Allocate a promise object.

Parameters

	task	The running task.
[out]	out_promise	The promise that was allocated.

Returns

The promise JS object.

tf_task_allocate_task_id()

taskid_t tf_task_allocate_task_id	(	tf_task_t *	task,
		tf_taskstub_t *	stub
	)

Generate an unused task identifier representing the task stub from the running task.

Parameters

task	The running task.
stub	A handle to the task requesting an identifier.

Returns

The new identifier.

tf_task_check_jobs()

void tf_task_check_jobs

(

tf_task_t *

task

)

Check for JS jobs that need to be run. Generally to be called post-JS_Call in tf_util_report_error.

Parameters

task

The task.

tf_task_configure_from_fd()

void tf_task_configure_from_fd	(	tf_task_t *	task,
		int	fd
	)

Configure a task from a file descriptor. Typically a pipe to the parent task's process.

Parameters

task	The task to configure.
fd	The file descriptor.

tf_task_create()

tf_task_t * tf_task_create

(

)

Create a task.

Returns

A new task.

tf_task_destroy()

void tf_task_destroy

(

tf_task_t *

task

)

Destroy a task.

Parameters

task

The task.

tf_task_execute()

int tf_task_execute	(	tf_task_t *	task,
		const char *	file
	)

Run a script from file on disk.

Parameters

task	The task.
file	The path to the script file to run.

Returns

0 if there was a problem or 1 if the script was started.

tf_task_export_function()

exportid_t tf_task_export_function	(	tf_task_t *	task,
		tf_taskstub_t *	to,
		JSValue	function
	)

Convert a function to an integer handle that can be passed across processes.

Parameters

task	The running task.
to	The task stub to which the handle will be passed.
function	The functoin to export.

Returns

A handle representing the function.

tf_task_get()

tf_task_t * tf_task_get

(

JSContext *

context

)

Get the task from a JS context.

Parameters

context

The context.

Returns

The task.

tf_task_get_android_start_service()

tf_android_start_service_t * tf_task_get_android_start_service

(

)

Get the callback registered for starting an Android service.

Returns

the callback.

tf_task_get_android_stop_service()

tf_android_stop_service_t * tf_task_get_android_stop_service

(

)

Get the callback registered for stopping an Android service.

Returns

the callback.

tf_task_get_context()

JSContext * tf_task_get_context

(

tf_task_t *

task

)

Get the JS context from a task.

Parameters

task

The task.

Returns

The context.

tf_task_get_debug()

char * tf_task_get_debug

(

tf_task_t *

task

)

Get a report of miscellaneous debug information.

Parameters

task

The task.

Returns

A JSON representation of various debug information that must be freed with tf_free().

tf_task_get_loop()

uv_loop_t * tf_task_get_loop

(

tf_task_t *

task

)

Get the event loop from a task.

Parameters

task

The task.

Returns

The loop.

tf_task_get_name()

const char * tf_task_get_name

(

tf_task_t *

task

)

Get the name of a task.

Parameters

task

The task.

Returns

The task's name as derived from the script it is running.

tf_task_get_one_proc()

bool tf_task_get_one_proc

(

tf_task_t *

task

)

Get whether this instance is configure to run in a single process.

Parameters

task	The running task.

Returns

true if all tasks are running in a single process.

tf_task_get_path_with_root()

const char * tf_task_get_path_with_root	(	tf_task_t *	task,
		const char *	path
	)

Get the path to use for reading a given loose file.

Parameters

task	The task.
path	The path to the file.

Returns

The path or NULL. Free with tf_free().

tf_task_get_root_path()

const char * tf_task_get_root_path

(

tf_task_t *

task

)

Get the path to use for reading loose files.

Parameters

task

The task.

Returns

The path or NULL.

tf_task_get_ssb()

tf_ssb_t * tf_task_get_ssb

(

tf_task_t *

task

)

Get the SSB instance from a task.

Parameters

task

The task.

Returns

The SSB instance.

tf_task_get_stub()

tf_taskstub_t * tf_task_get_stub	(	tf_task_t *	task,
		taskid_t	id
	)

Get a tf_taskstub_t by taskid_t.

Parameters

task	The task.
id	The id.

Returns

The task stub or NULL.

tf_task_get_trace()

tf_trace_t * tf_task_get_trace

(

tf_task_t *

task

)

Get the trace instance from a task.

Parameters

task

The task.

Returns

The trace instance.

tf_task_get_zip_path()

const char * tf_task_get_zip_path

(

tf_task_t *

task

)

Get the path to the zip file being used for static data.

Parameters

task

The task.

Returns

The zip file path or NULL.

tf_task_is_shutting_down()

bool tf_task_is_shutting_down

(

tf_task_t *

task

)

Check whether tf_task_destroy has been called already.

Parameters

task

The task.

Returns

true if the task is in the process of shutting down.

tf_task_on_receive_packet()

void tf_task_on_receive_packet	(	int	packetType,
		const char *	begin,
		size_t	length,
		void *	userData
	)

Have a task handle a message from a packaet stream.

Parameters

packetType	The type of the message.
begin	The data.
length	The size of the data.
userData	The task stub from which the packet was received.

tf_task_print()

void tf_task_print	(	tf_task_t *	task,
		int	argc,
		JSValueConst *	argv
	)

Print through a task's parent.

Parameters

task	The running task.
argc	The number of arguments to print.
argv	The arguments to print.

tf_task_reject_promise()

void tf_task_reject_promise	(	tf_task_t *	task,
		promiseid_t	promise,
		JSValue	error
	)

Reject a promise.

Parameters

task	The running task.
promise	The promise to reject.
error	The value with which to reject the promise.

tf_task_remove_child()

void tf_task_remove_child	(	tf_task_t *	task,
		tf_taskstub_t *	child
	)

Remove a task stub from a task.

Parameters

task	The parent task.
child	The task handle to remove.

tf_task_resolve_promise()

void tf_task_resolve_promise	(	tf_task_t *	task,
		promiseid_t	promise,
		JSValue	result
	)

Resolve a promise.

Parameters

task	The running task.
promise	The promise to resolve.
result	The value with which to resolve the promise.

tf_task_run()

void tf_task_run

(

tf_task_t *

task

)

Update a task until it is done or stopped.

Parameters

task

The task.

tf_task_send_error_to_parent()

bool tf_task_send_error_to_parent	(	tf_task_t *	task,
		JSValue	error
	)

Send an error to the parent task.

Parameters

task	The current task.
error	The potential error.

Returns

true If the object was an error or exception and it was passed to the parent task.

tf_task_send_promise_message()

void tf_task_send_promise_message	(	tf_task_t *	from,
		tf_taskstub_t *	to,
		tf_task_message_t	type,
		promiseid_t	promise,
		JSValue	payload
	)

Send a message referencing a promise across a packet stream.

Parameters

from	The task originating the message.
to	The task handle receiving the message.
type	The message type.
promise	The promise.
payload	The content of the message.

tf_task_set_android_service_callbacks()

void tf_task_set_android_service_callbacks	(	tf_android_start_service_t *	start_service,
		tf_android_stop_service_t *	stop_service
	)

Set Android service callbacks.

Parameters

start_service	Start service callback.
stop_service	Stop service callback.

tf_task_set_args()

void tf_task_set_args	(	tf_task_t *	task,
		const char *	args
	)

Set arbitrary named arguments that will be made available to the task.

Parameters

task	The task.
args	A string of the form "key=value,other_key=other_value,..."

tf_task_set_db_path()

void tf_task_set_db_path	(	tf_task_t *	task,
		const char *	path
	)

Set the path to the SQLite database.

Parameters

task	The task.
path	The database path.

tf_task_set_one_proc()

void tf_task_set_one_proc	(	tf_task_t *	task,
		bool	one_proc
	)

Set whether all tasks should run in a single process. Only supported to appease Apple's limitations.

Parameters

task	The running task.
one_proc	True if subprocesses should not be used.

tf_task_set_root_path()

void tf_task_set_root_path	(	tf_task_t *	task,
		const char *	path
	)

Set the path to the root of the project directory for data.

Parameters

task	The task.
path	The file path or NULL.

tf_task_set_ssb_network_key()

void tf_task_set_ssb_network_key	(	tf_task_t *	task,
		const char *	network_key
	)

Set the SSB network key.

Parameters

task	The task.
network_key	The network key.

tf_task_set_trusted()

void tf_task_set_trusted	(	tf_task_t *	task,
		bool	trusted
	)

Set a task as trusted or untrusted. Trusted tasks have more interface exposed to them.

Parameters

task	The task.
trusted	true if the task is trusted.

tf_task_set_zip_path()

void tf_task_set_zip_path	(	tf_task_t *	task,
		const char *	path
	)

Set the path to a zip file from which to load all static data.

Parameters

task	The task.
path	The zip file path or NULL.

tf_task_visit_children()

void tf_task_visit_children	(	tf_task_t *	task,
		void(*)(tf_task_t *task, tf_taskstub_t *stub, void *user_data)	callback,
		void *	user_data
	)

Call a callback for each child task.

Parameters

task	The task.
callback	The callback.
user_data	User data to pass to the callback.