Port API

Reference

Termination

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.

/**
* 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.
*/voidjerry_port_fatal(jerry_fatal_code_tcode);

I/O

These are the only I/O functions jerry calls.

/**
* Jerry log levels. The levels are in severity order
* where the most serious levels come first.
*/typedefenum{JERRY_LOG_LEVEL_ERROR,/**< the engine will terminate after the message is printed */JERRY_LOG_LEVEL_WARNING,/**< a request is aborted, but the engine continues its operation */JERRY_LOG_LEVEL_DEBUG,/**< debug messages from the engine, low volume */JERRY_LOG_LEVEL_TRACE/**< detailed info about engine internals, potentially high volume */}jerry_log_level_t;/**
* Display or log a debug/error message, and sends it to the debugger client as well.
* The function should implement a printf-like interface, where the first argument
* specifies the log level and the second argument specifies a format string on how
* to stringify the rest of the parameter list.
*
* This function is only 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).
*
* It should be the port that decides whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*
* Example: a libc-based port may implement this with vfprintf(stderr) or
* vfprintf(logfile), or both, depending on log level.
*
* Note:
* This port function is called by jerry-core when JERRY_ENABLE_LOGGING is
* defined. It is also common practice though to use this function in
* application code.
*/voidjerry_port_log(jerry_log_level_tlevel,constchar*fmt,...);

Date

/**
* Get local time zone adjustment, in milliseconds, for the given timestamp.
* The timestamp can be specified in either UTC or local time, depending on
* the value of is_utc. Adding the value returned from this function to
* a timestamp in UTC time should result in local time for the current time
* zone, and subtracting it from a timestamp in local time should result in
* UTC time.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 20.3.1.7 of the ECMAScript version 9.0 spec.
*
* See Also:
* ECMA-262 v9, 20.3.1.7
*
* Note:
* This port function is called by jerry-core when
* CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. Otherwise this function is
* not used.
*
* @param unix_ms The unix timestamp we want an offset for, given in
* millisecond precision (could be now, in the future,
* or in the past). As with all unix timestamps, 0 refers to
* 1970-01-01, a day is exactly 86 400 000 milliseconds, and
* leap seconds cause the same second to occur twice.
* @param is_utc Is the given timestamp in UTC time? If false, it is in local
* time.
*
* @return milliseconds between local time and UTC for the given timestamp,
* if available
*. 0 if not available / we are in UTC.
*/doublejerry_port_get_local_time_zone_adjustment(doubleunix_ms,boolis_utc);/**
* Get system time
*
* Note:
* This port function is called by jerry-core when
* CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. It is also common practice
* in application code to use this function for the initialization of the
* random number generator.
*
* @return milliseconds since Unix epoch
*/doublejerry_port_get_current_time(void);

External context

Allow 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.

/**
* Get the current context of the engine. Each port should provide its own
* implementation of this interface.
*
* Note:
* This port function is called by jerry-core when
* JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not
* used.
*
* @return the pointer to the engine context.
*/structjerry_context_t*jerry_port_get_current_context(void);

Sleep

/**
* Makes the process sleep for a given time.
*
* Note:
* This port function is called by jerry-core when JERRY_DEBUGGER is
* defined. Otherwise this function is not used.
*
* @param sleep_time milliseconds to sleep.
*/voidjerry_port_sleep(uint32_tsleep_time);

How to port JerryScript

This section describes a basic port implementation which was created for Unix based systems.

External context

#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
/**
* Pointer to the current context.
* Note that it is a global variable, and is not a thread safe implementation.
*/staticjerry_context_t*current_context_p=NULL;/**
* Set the current_context_p as the passed pointer.
*/voidjerry_port_default_set_current_context(jerry_context_t*context_p)/**< points to the created context */{current_context_p=context_p;}/* jerry_port_default_set_current_context *//**
* Get the current context.
*
* @return the pointer to the current context
*/jerry_context_t*jerry_port_get_current_context(void){returncurrent_context_p;}/* jerry_port_get_current_context */