More docs.

This commit is contained in:
Cory McWilliams 2024-03-01 21:18:12 -05:00
parent a710c30572
commit f0a871e1f8
3 changed files with 297 additions and 8 deletions

View File

@ -949,9 +949,6 @@ char* tf_task_get_disconnections(tf_task_t* task)
return result; return result;
} }
char* tf_task_get_debug(tf_task_t* task);
char* tf_task_get_hitches(tf_task_t* task);
static JSValue _tf_task_getFile(JSContext* context, JSValueConst this_val, int argc, JSValueConst* argv) static JSValue _tf_task_getFile(JSContext* context, JSValueConst this_val, int argc, JSValueConst* argv)
{ {
tf_task_t* task = JS_GetContextOpaque(context); tf_task_t* task = JS_GetContextOpaque(context);

View File

@ -13,19 +13,30 @@
#include "quickjs.h" #include "quickjs.h"
/** An event loop. */
typedef struct uv_loop_s uv_loop_t; typedef struct uv_loop_s uv_loop_t;
/** A timer. */
typedef struct uv_timer_s uv_timer_t; typedef struct uv_timer_s uv_timer_t;
/** A task identifier. */
typedef int taskid_t; typedef int taskid_t;
/** A promise identifier. */
typedef int promiseid_t; typedef int promiseid_t;
/** An exported function identifier. */
typedef int exportid_t; typedef int exportid_t;
/** A handle to a task. */
typedef struct _tf_taskstub_t tf_taskstub_t; typedef struct _tf_taskstub_t tf_taskstub_t;
/** A task. */
typedef struct _tf_task_t tf_task_t; typedef struct _tf_task_t tf_task_t;
/** A trace instance. */
typedef struct _tf_trace_t tf_trace_t; typedef struct _tf_trace_t tf_trace_t;
/** An SSB instance. */
typedef struct _tf_ssb_t tf_ssb_t; typedef struct _tf_ssb_t tf_ssb_t;
/** The fixed ID of the parent task. */
static const taskid_t k_task_parent_id = 0; static const taskid_t k_task_parent_id = 0;
/** A message type that can be sent between tasks. */
typedef enum _tf_task_message_t typedef enum _tf_task_message_t
{ {
kResolvePromise, kResolvePromise,
@ -44,50 +55,275 @@ typedef enum _tf_task_message_t
kPrint, kPrint,
} tf_task_message_t; } tf_task_message_t;
/**
** Create a task.
** @return A new task.
*/
tf_task_t* tf_task_create(); tf_task_t* tf_task_create();
/**
** Configure a task from a file descriptor. Typically a pipe to the parent
** task's process.
** @param task The task to configure.
** @param fd The file descriptor.
*/
void tf_task_configure_from_fd(tf_task_t* task, int fd); void tf_task_configure_from_fd(tf_task_t* task, int fd);
/**
** Set the port number on which to run an SSB secure handshake server.
** @param task The task.
** @param port The port number or 0 to disable.
*/
void tf_task_set_ssb_port(tf_task_t* task, int port); void tf_task_set_ssb_port(tf_task_t* task, int port);
/**
** Set the port number on which to run an HTTP server.
** @param task The task.
** @param port The port number of 0 to disable.
*/
void tf_task_set_http_port(tf_task_t* task, int port); void tf_task_set_http_port(tf_task_t* task, int port);
/**
** Set the port number on which to run an HTTPS server.
** @param task The task.
** @param port The port number of 0 to disable.
*/
void tf_task_set_https_port(tf_task_t* task, int port); void tf_task_set_https_port(tf_task_t* task, int port);
/**
** Set the path to the SQLite database.
** @param task The task.
** @param path The database path.
*/
void tf_task_set_db_path(tf_task_t* task, const char* path); void tf_task_set_db_path(tf_task_t* task, const char* path);
/**
** Set the path to a zip file from which to load all static data.
** @param task The task.
** @param path The zip file path or NULL.
*/
void tf_task_set_zip_path(tf_task_t* task, const char* path); void tf_task_set_zip_path(tf_task_t* task, const char* path);
/**
** Get the path to the zipp file being used for static data.
** @param task The task.
** @return The zip file path or NULL.
*/
const char* tf_task_get_zip_path(tf_task_t* task); const char* tf_task_get_zip_path(tf_task_t* task);
/**
** Set arbitrary named arguments that will be made available to the task.
** @param task The task.
** @param args A string of the form "key=value,other_key=other_value,..."
*/
void tf_task_set_args(tf_task_t* task, const char* args); void tf_task_set_args(tf_task_t* task, const char* args);
/**
** Get whether this instance is configure to run in a single process.
** @param task The running task.
** @return true if all tasks are running in a single process.
*/
bool tf_task_get_one_proc(tf_task_t* task); bool tf_task_get_one_proc(tf_task_t* task);
/**
** Set whether all tasks should run in a single process. Only supported to
** appease Apple's limitations.
** @param task The running task.
** @param one_proc True if subprocesses should not be used.
*/
void tf_task_set_one_proc(tf_task_t* task, bool one_proc); void tf_task_set_one_proc(tf_task_t* task, bool one_proc);
/**
** Start a task running its script.
** @param task The task.
*/
void tf_task_activate(tf_task_t* task); void tf_task_activate(tf_task_t* task);
/**
** Update a task until it is done or stopped.
** @param task The task.
*/
void tf_task_run(tf_task_t* task); void tf_task_run(tf_task_t* task);
/**
** Run a script from file on disk.
** @param task The task.
** @param file The path to the script file to run.
** @return 0 if there was a problem or 1 if the script was started.
*/
int tf_task_execute(tf_task_t* task, const char* file); int tf_task_execute(tf_task_t* task, const char* file);
/**
** Set a task as trusted or untrusted. Trusted tasks have more interface exposed to them.
** @param task The task.
** @param trusted true if the task is trusted.
*/
void tf_task_set_trusted(tf_task_t* task, bool trusted); void tf_task_set_trusted(tf_task_t* task, bool trusted);
/**
** Get the JS context from a task.
** @param task The task.
** @return The context.
*/
JSContext* tf_task_get_context(tf_task_t* task); JSContext* tf_task_get_context(tf_task_t* task);
/**
** Destroy a task.
** @param task The task.
*/
void tf_task_destroy(tf_task_t* task); void tf_task_destroy(tf_task_t* task);
/**
** Convert a function to an integer handle that can be passed across processes.
** @param task The running task.
** @param to The task stub to which the handle will be passed.
** @param function The functoin to export.
** @return A handle representing the function.
*/
exportid_t tf_task_export_function(tf_task_t* task, tf_taskstub_t* to, JSValue function); exportid_t tf_task_export_function(tf_task_t* task, tf_taskstub_t* to, JSValue function);
/**
** Create a function that can be called from a handle to an exported function
** from another task.
** @param task The running task.
** @param stub_id The task stub from which the function was exported.
** @param export_id The handle to the function.
** @return A function that, when called, invokes the corresponding function in
** the remote task.
*/
JSValue tf_task_add_import(tf_task_t* task, taskid_t stub_id, exportid_t export_id); JSValue tf_task_add_import(tf_task_t* task, taskid_t stub_id, exportid_t export_id);
/**
** Get the event loop from a task.
** @param task The task.
** @return The loop.
*/
uv_loop_t* tf_task_get_loop(tf_task_t* task); uv_loop_t* tf_task_get_loop(tf_task_t* task);
/**
** Get the task from a JS context.
** @param context The context.
** @return The task.
*/
tf_task_t* tf_task_get(JSContext* context); tf_task_t* tf_task_get(JSContext* context);
/**
** Get the trace instance from a task.
** @param task The task.
** @return The trace instance.
*/
tf_trace_t* tf_task_get_trace(tf_task_t* task); tf_trace_t* tf_task_get_trace(tf_task_t* task);
/**
** Get the SSB instance from a task.
** @param task The task.
** @return The SSB instance.
*/
tf_ssb_t* tf_task_get_ssb(tf_task_t* task); tf_ssb_t* tf_task_get_ssb(tf_task_t* task);
/**
** Get the name of a task.
** @param task The task.
** @return The task's name as derived from the script it is running.
*/
const char* tf_task_get_name(tf_task_t* task); const char* tf_task_get_name(tf_task_t* task);
/**
** Print through a task's parent.
** @param task The running task.
** @param argc The number of arguments to print.
** @param argv The arguments to print.
*/
void tf_task_print(tf_task_t* task, int argc, JSValueConst* argv); void tf_task_print(tf_task_t* task, int argc, JSValueConst* argv);
/**
** Allocate a promise object.
** @param task The running task.
** @param[out] out_promise The promise that was allocated.
** @return The promise JS object.
*/
JSValue tf_task_allocate_promise(tf_task_t* task, promiseid_t* out_promise); JSValue tf_task_allocate_promise(tf_task_t* task, promiseid_t* out_promise);
/**
** Reject a promise.
** @param task The running task.
** @param promise The promise to reject.
** @param error The value with which to reject the promise.
*/
void tf_task_reject_promise(tf_task_t* task, promiseid_t promise, JSValue error); void tf_task_reject_promise(tf_task_t* task, promiseid_t promise, JSValue error);
/**
** Resolve a promise.
** @param task The running task.
** @param promise The promise to resolve.
** @param result The value with which to resolve the promise.
*/
void tf_task_resolve_promise(tf_task_t* task, promiseid_t promise, JSValue result); void tf_task_resolve_promise(tf_task_t* task, promiseid_t promise, JSValue result);
/**
** Send a message referencing a promise across a packet stream.
** @param from The task originating the message.
** @param to The task handle receiving the message.
** @param type The message type.
** @param promise The promise.
** @param payload The content of the 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); void tf_task_send_promise_message(tf_task_t* from, tf_taskstub_t* to, tf_task_message_t type, promiseid_t promise, JSValue payload);
/**
** Have a task handle a message from a packaet stream.
** @param packetType The type of the message.
** @param begin The data.
** @param length The size of the data.
** @param userData The task stub from which the packet was received.
*/
void tf_task_on_receive_packet(int packetType, const char* begin, size_t length, void* userData); void tf_task_on_receive_packet(int packetType, const char* begin, size_t length, void* userData);
/**
** Generate an unused task identifier representing the task stub from the running task.
** @param task The running task.
** @param stub A handle to the task requesting an identifier.
** @return The new identifier.
*/
taskid_t tf_task_allocate_task_id(tf_task_t* task, tf_taskstub_t* stub); taskid_t tf_task_allocate_task_id(tf_task_t* task, tf_taskstub_t* stub);
/**
** Remove a task stub from a task.
** @param task The parent task.
** @param child The task handle to remove.
*/
void tf_task_remove_child(tf_task_t* task, tf_taskstub_t* child); void tf_task_remove_child(tf_task_t* task, tf_taskstub_t* child);
void tf_task_report_error(tf_task_t* task, JSValue error); /**
** Send an error to the parent task.
JSValue tf_try_get_typed_array_buffer(JSContext* ctx, JSValueConst obj, size_t* pbyte_offset, size_t* pbyte_length, size_t* pbytes_per_element); ** @param task The current task.
uint8_t* tf_try_get_array_buffer(JSContext* ctx, size_t* psize, JSValueConst obj); ** @param error The potential error.
** @return true If the object was an error or exception and it was passed to
** the parent task.
*/
bool tf_task_send_error_to_parent(tf_task_t* task, JSValue error); bool tf_task_send_error_to_parent(tf_task_t* task, JSValue error);
/**
** Get a report of recent disconnections.
** @param task The task.
** @return A JSON representation of recent disconnections that must be freed
** with tf_free().
*/
char* tf_task_get_disconnections(tf_task_t* task); char* tf_task_get_disconnections(tf_task_t* task);
/**
** Get a report of miscellaneous debug information.
** @param task The task.
** @return A JSON representation of various debug information that must be
** freed with tf_free().
*/
char* tf_task_get_debug(tf_task_t* task); char* tf_task_get_debug(tf_task_t* task);
/**
** Get a report of hitches that occurred.
** @param task The task.
** @return A JSON report of recent hitches that must be freed with tf_free().
*/
char* tf_task_get_hitches(tf_task_t* task); char* tf_task_get_hitches(tf_task_t* task);
/** @} */ /** @} */

View File

@ -10,20 +10,76 @@
#include "quickjs.h" #include "quickjs.h"
#include "uv.h" #include "uv.h"
/** A task identifier. */
typedef int taskid_t; typedef int taskid_t;
/** A packet stream. */
typedef struct _tf_packetstream_t tf_packetstream_t; typedef struct _tf_packetstream_t tf_packetstream_t;
/** A task. */
typedef struct _tf_task_t tf_task_t; typedef struct _tf_task_t tf_task_t;
/** A handle to another task. */
typedef struct _tf_taskstub_t tf_taskstub_t; typedef struct _tf_taskstub_t tf_taskstub_t;
/** Initialize task stub. Call before using the rest. */
void tf_taskstub_startup(); void tf_taskstub_startup();
/**
** Register the task stub script interface.
** @param context The JS context.
** @return The task stub constructor.
*/
JSValue tf_taskstub_register(JSContext* context); JSValue tf_taskstub_register(JSContext* context);
/**
** Get a unique identifier for the task stub.
** @param stub The task stub.
** @return An identifier for the stub.
*/
taskid_t tf_taskstub_get_id(const tf_taskstub_t* stub); taskid_t tf_taskstub_get_id(const tf_taskstub_t* stub);
/**
** Get the JS object representing the task stub.
** @param stub The task stub.
** @return The JS object.
*/
JSValue tf_taskstub_get_task_object(const tf_taskstub_t* stub); JSValue tf_taskstub_get_task_object(const tf_taskstub_t* stub);
/**
** Get the packet stream that can be used to communicate with the task stub.
** @param stub The task stub.
** @return The packet stream.
*/
tf_packetstream_t* tf_taskstub_get_stream(const tf_taskstub_t* stub); tf_packetstream_t* tf_taskstub_get_stream(const tf_taskstub_t* stub);
/**
** Get the task owning the task stub.
** @param stub The task stub.
** @return The task from which the task stub was created.
*/
tf_task_t* tf_taskstub_get_owner(const tf_taskstub_t* stub); tf_task_t* tf_taskstub_get_owner(const tf_taskstub_t* stub);
/**
** Create a task stub representing the parent task of the running process.
** @param task The running task.
** @param file A file descriptor of a pipe connected to a parent process task.
** @return The created task stub.
*/
tf_taskstub_t* tf_taskstub_create_parent(tf_task_t* task, uv_file file); tf_taskstub_t* tf_taskstub_create_parent(tf_task_t* task, uv_file file);
/**
** Report an error to a task stub.
** @param stub The stub to which to report th eerror.
** @param error The error to report.
*/
void tf_taskstub_on_error(tf_taskstub_t* stub, JSValue error); void tf_taskstub_on_error(tf_taskstub_t* stub, JSValue error);
/**
** Print to a task stub.
** @param stub The task stub to which to print.
** @param arguments The values to print.
*/
void tf_taskstub_on_print(tf_taskstub_t* stub, JSValue arguments); void tf_taskstub_on_print(tf_taskstub_t* stub, JSValue arguments);
/** @} */ /** @} */