It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function.
/**
* Init the program
*/
void jerry_port_init (void);/**
* Signal the port that jerry experienced a fatal failure from which it cannot
* recover.
*
* @param code gives the cause of the error.
*
* Note:
* Jerry expects the function not to return.
*
* Example: a libc-based port may implement this with exit() or abort(), or both.
*/
void jerry_port_fatal (jerry_fatal_code_t code);The path style of the OS
typedef enum
{
JERRY_STYLE_WINDOWS,
JERRY_STYLE_UNIX,
} jerry_path_style_t;Error codes
typedef enum
{
JERRY_FATAL_OUT_OF_MEMORY = 10,
JERRY_FATAL_REF_COUNT_LIMIT = 12,
JERRY_FATAL_DISABLED_BYTE_CODE = 13,
JERRY_FATAL_UNTERMINATED_GC_LOOPS = 14,
JERRY_FATAL_FAILED_ASSERTION = 120
} jerry_fatal_code_t;/**
* Makes the process sleep for a given time.
*
* Note:
* This port function is called by jerry-core when JERRY_DEBUGGER is set to 1.
* Otherwise this function is not used.
*
* @param sleep_time milliseconds to sleep.
*/
void jerry_port_sleep (uint32_t sleep_time);Allows the user to provide external buffer for isolated engine contexts, so that user can configure the heap size at runtime and run multiple JS applications simultaneously.
/**
* Allocate a new context for the engine.
*
* This port function is called by jerry_init when JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
* used. The engine will pass the size required for the context structure. An implementation must make sure to
* allocate at least this amount.
*
* Excess allocated space will be used as the engine heap when jerryscript is configured to use it's internal allocator,
* this can be used to control the internal heap size.
*
* NOTE: The allocated memory must be pointer-aligned, otherwise the behavior is
* undefined.
*
* @param context_size: the size of the internal context structure
*
* @return total size of the allocated buffer
*/
size_t jerry_port_context_alloc (size_t context_size);/**
* Get the currently active context of the engine.
*
* This port function is called by jerry-core when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the currently used engine context.
*/
struct jerry_context_t *jerry_port_context_get (void);/**
* Free the currently used context.
*
* This port function is called by jerry_cleanup when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the engine context.
*/
void jerry_port_context_free (void);/**
* Display or log a debug/error message.
*
* The message is passed as a zero-terminated string. Messages may be logged in parts, which
* will result in multiple calls to this functions. The implementation should consider
* this before appending or prepending strings to the argument.
*
* This function is called with messages coming from the jerry engine as
* the result of some abnormal operation or describing its internal operations
* (e.g., data structure dumps or tracing info).
*
* The implementation can decide whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*
* @param message_p: the message to log.
*/
void jerry_port_log (const char *message_p);/**
* Print a buffer to standard output
*
* This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
* information.
*
* @param buffer_p: input buffer
* @param buffer_size: data size
*/
void jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size);/**
* Read a line from standard input.
*
* The implementation should allocate storage necessary for the string. The result string should include the ending line
* terminator character(s) and should be zero terminated.
*
* An implementation may return NULL to signal that the end of input is reached, or an error occured.
*
* When a non-NULL value is returned, the caller will pass the returned value to `jerry_port_line_free` when the line is
* no longer needed. This can be used to finalize dynamically allocated buffers if necessary.
*
* This port function is never called from jerry-core directly, it is only used by some jerry-ext components that
* require user input.
*
* @param out_size_p: size of the input string in bytes, excluding terminating zero byte
*
* @return pointer to the buffer storing the string,
* or NULL if end of input
*/
jerry_char_t *jerry_port_line_read (jerry_size_t *out_size_p);/**
* Free a line buffer allocated by jerry_port_line_read
*
* @param buffer_p: buffer returned by jerry_port_line_read
*/
void jerry_port_line_free (jerry_char_t *buffer_p);/**
* Get the path style of the current OS
*
* @return path style
*/
jerry_path_style_t jerry_port_path_style (void);/**
* Get the cwd, the output string will be zero-terminated
*
* @param buffer_p: the buffer to storage the cwd
* @param buffer_size: the `buffer_p` buffer size, including '\0` terminator
*
* @note
* - cwd: current working directory
*
* @return The length of cwd, excluding '\0' terminator
* - When buffer_p is `NULL` and get cwd succeed return length of cwd
* - When buffer_p is `NULL` and get cwd failed return 0
* - When buffer_p is not `NULL` and the `buffer_size - 1` just equal to
* length of cwd; and get cwd succeed return `buffer_size - 1`.
* - Otherwise means get cwd failed and return 0
*/
jerry_size_t jerry_port_get_cwd (jerry_char_t *buffer_p, jerry_size_t buffer_size);/**
* Open a source file and read its contents into a buffer.
*
* When the source file is no longer needed by the caller, the returned pointer will be passed to
* `jerry_port_source_free`, which can be used to finalize the buffer.
*
* @param file_name_p: Path that points to the source file in the filesystem.
* @param out_size_p: The opened file's size in bytes.
*
* @return pointer to the buffer which contains the content of the file.
*/
jerry_char_t *jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p);/**
* Free a source file buffer.
*
* @param buffer_p: buffer returned by jerry_port_source_read
*/
void jerry_port_source_free (jerry_char_t *buffer_p);/**
* Get local time zone adjustment in milliseconds for the given input time.
*
* The argument is a time value representing milliseconds since unix epoch.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 21.4.1.7 of the ECMAScript version 12.0, as if called with isUTC true.
*
* This port function can be called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* Otherwise this function is not used.
*
* @param unix_ms: time value in milliseconds since unix epoch
*
* @return local time offset in milliseconds applied to UTC for the given time value
*/
int32_t jerry_port_local_tza (double unix_ms);/**
* Get the current system time in UTC.
*
* This port function is called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* It can also be used in the implementing application to initialize the random number generator.
*
* @return milliseconds since Unix epoch
*/
double jerry_port_current_time (void);