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.

  1. /**
  2.  * Signal the port that jerry experienced a fatal failure from which it cannot
  3.  * recover.
  4.  *
  5.  * @param code gives the cause of the error.
  6.  *
  7.  * Note:
  8.  *      Jerry expects the function not to return.
  9.  *
  10.  * Example: a libc-based port may implement this with exit() or abort(), or both.
  11.  */
  12. void jerry_port_fatal (jerry_fatal_code_t code);

Error codes

  1. typedef enum
  2. {
  3.   ERR_OUT_OF_MEMORY = 10,
  4.   ERR_REF_COUNT_LIMIT = 12,
  5.   ERR_DISABLED_BYTE_CODE = 13,
  6.   ERR_FAILED_INTERNAL_ASSERTION = 120
  7. } jerry_fatal_code_t;

I/O

These are the only I/O functions jerry calls.

  1. /**
  2.  * Jerry log levels. The levels are in severity order
  3.  * where the most serious levels come first.
  4.  */
  5. typedef enum
  6. {
  7.   JERRY_LOG_LEVEL_ERROR,    /**< the engine will terminate after the message is printed */
  8.   JERRY_LOG_LEVEL_WARNING,  /**< a request is aborted, but the engine continues its operation */
  9.   JERRY_LOG_LEVEL_DEBUG,    /**< debug messages from the engine, low volume */
  10.   JERRY_LOG_LEVEL_TRACE     /**< detailed info about engine internals, potentially high volume */
  11. } jerry_log_level_t;
  13. /**
  14.  * Display or log a debug/error message, and sends it to the debugger client as well.
  15.  * The function should implement a printf-like interface, where the first argument
  16.  * specifies the log level and the second argument specifies a format string on how
  17.  * to stringify the rest of the parameter list.
  18.  *
  19.  * This function is only called with messages coming from the jerry engine as
  20.  * the result of some abnormal operation or describing its internal operations
  21.  * (e.g., data structure dumps or tracing info).
  22.  *
  23.  * It should be the port that decides whether error and debug messages are logged to
  24.  * the console, or saved to a database or to a file.
  25.  *
  26.  * Example: a libc-based port may implement this with vfprintf(stderr) or
  27.  * vfprintf(logfile), or both, depending on log level.
  28.  *
  29.  * Note:
  30.  *      This port function is called by jerry-core when JERRY_LOGGING is
  31.  *      enabled. It is also common practice though to use this function in
  32.  *      application code.
  33.  */
  34. void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);

The jerry_port_print_char is currenlty not used by the jerry-core directly. However, it provides a port specifc way for jerry-ext components to print information.

  1. /**
  2.  * Print a character to stdout.
  3.  */
  4. void jerry_port_print_char (char c);

ES2015 Module system

The port API provides functions that can be used by the module system to open and close source files, and normalize file paths. The jerry_port_get_native_module port function can be used to provide native modules to the engine. This function will be called when an import/export statement is encountered with an unknown module specifier, which embedders can use to supply native module objects based on the module name argument.

  1. /**
  2.  * Opens file with the given path and reads its source.
  3.  * @return the source of the file
  4.  */
  5. uint8_t *
  6. jerry_port_read_source (const char *file_name_p, /**< file name */
  7.                         size_t *out_size_p) /**< [out] read bytes */
  8. {
  9.   // open file from given path
  10.   // return its source
  11. } /* jerry_port_read_source */
  13. /**
  14.  * Release the previously opened file's content.
  15.  */
  16. void
  17. jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
  18. {
  19.   free (buffer_p);
  20. } /* jerry_port_release_source */
  22. /**
  23.  * Normalize a file path
  24.  *
  25.  * @return length of the path written to the output buffer
  26.  */
  27. size_t
  28. jerry_port_normalize_path (const char *in_path_p, /**< input file path */
  29.                            char *out_buf_p,       /**< output buffer */
  30.                            size_t out_buf_size,   /**< size of output buffer */
  31.                            char *base_file_p)     /**< base file path */
  32. {
  33.   // normalize in_path_p by expanding relative paths etc.
  34.   // if base_file_p is not NULL, in_path_p is relative to that file
  35.   // write to out_buf_p the normalized path
  36.   // return length of written path
  37. } /* jerry_port_normalize_path */
  39. /**
  40.  * Get the module object of a native module.
  41.  *
  42.  * Note:
  43.  *      This port function is called by jerry-core when ES2015_MODULE_SYSTEM
  44.  *      is enabled.
  45.  *
  46.  * @param name String value of the module specifier.
  47.  *
  48.  * @return Undefined, if 'name' is not a native module
  49.  *         jerry_value_t containing the module object, otherwise
  50.  */
  51. jerry_value_t
  52. jerry_port_get_native_module (jerry_value_t name) /**< module specifier */
  53. {
  54.   (void) name;
  55.   return jerry_create_undefined ();
  56. }

Date

  1. /**
  2.  * Get local time zone adjustment, in milliseconds, for the given timestamp.
  3.  * The timestamp can be specified in either UTC or local time, depending on
  4.  * the value of is_utc. Adding the value returned from this function to
  5.  * a timestamp in UTC time should result in local time for the current time
  6.  * zone, and subtracting it from a timestamp in local time should result in
  7.  * UTC time.
  8.  *
  9.  * Ideally, this function should satisfy the stipulations applied to LocalTZA
  10.  * in section 20.3.1.7 of the ECMAScript version 9.0 spec.
  11.  *
  12.  * See Also:
  13.  *          ECMA-262 v9, 20.3.1.7
  14.  *
  15.  * Note:
  16.  *      This port function is called by jerry-core when
  17.  *      JERRY_BUILTIN_DATE is set to 1. Otherwise this function is
  18.  *      not used.
  19.  *
  20.  * @param unix_ms The unix timestamp we want an offset for, given in
  21.  *                millisecond precision (could be now, in the future,
  22.  *                or in the past). As with all unix timestamps, 0 refers to
  23.  *                1970-01-01, a day is exactly 86 400 000 milliseconds, and
  24.  *                leap seconds cause the same second to occur twice.
  25.  * @param is_utc Is the given timestamp in UTC time? If false, it is in local
  26.  *               time.
  27.  *
  28.  * @return milliseconds between local time and UTC for the given timestamp,
  29.  *         if available
  30.  *.        0 if not available / we are in UTC.
  31.  */
  32. double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
  34. /**
  35.  * Get system time
  36.  *
  37.  * Note:
  38.  *      This port function is called by jerry-core when
  39.  *      JERRY_BUILTIN_DATE is set to 1. It is also common practice
  40.  *      in application code to use this function for the initialization of the
  41.  *      random number generator.
  42.  *
  43.  * @return milliseconds since Unix epoch
  44.  */
  45. double jerry_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.

  1. /**
  2.  * Get the current context of the engine. Each port should provide its own
  3.  * implementation of this interface.
  4.  *
  5.  * Note:
  6.  *      This port function is called by jerry-core when
  7.  *      JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
  8.  *      used.
  9.  *
  10.  * @return the pointer to the engine context.
  11.  */
  12. struct jerry_context_t *jerry_port_get_current_context (void);

Sleep

  1. /**
  2.  * Makes the process sleep for a given time.
  3.  *
  4.  * Note:
  5.  *      This port function is called by jerry-core when JERRY_DEBUGGER is set to 1.
  6.  *      Otherwise this function is not used.
  7.  *
  8.  * @param sleep_time milliseconds to sleep.
  9.  */
  10. void jerry_port_sleep (uint32_t sleep_time);

How to port JerryScript

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

Termination

  1. #include <stdlib.h>
  2. #include "jerryscript-port.h"
  4. /**
  5.  * Default implementation of jerry_port_fatal.
  6.  */
  7. void jerry_port_fatal (jerry_fatal_code_t code)
  8. {
  9.   exit (code);
  10. } /* jerry_port_fatal */

I/O

  1. #include <stdarg.h>
  2. #include "jerryscript-port.h"
  4. /**
  5.  * Provide log message implementation for the engine.
  6.  *
  7.  * Note:
  8.  *      This example ignores the log level.
  9.  */
  10. void
  11. jerry_port_log (jerry_log_level_t level, /**< log level */
  12.                 const char *format, /**< format string */
  13.                 ...)  /**< parameters */
  14. {
  15.   va_list args;
  16.   va_start (args, format);
  17.   vfprintf (stderr, format, args);
  18.   va_end (args);
  19. } /* jerry_port_log */
  1. /**
  2.  * Print a character to stdout with putchar.
  3.  */
  4. void
  5. jerry_port_print_char (char c)
  6. {
  7.   putchar (c);
  8. } /* jerr_port_print_char */

Date

  1. #include <time.h>
  2. #include <sys/time.h>
  3. #include "jerryscript-port.h"
  5. /**
  6.  * Default implementation of jerry_port_get_local_time_zone_adjustment.
  7.  */
  8. double jerry_port_get_local_time_zone_adjustment (double unix_ms, /**< ms since unix epoch */
  9.                                                   bool is_utc)    /**< is the time above in UTC? */
  10. {
  11.   struct tm tm;
  12.   time_t now = (time_t) (unix_ms / 1000);
  13.   localtime_r (&now, &tm);
  14.   if (!is_utc)
  15.   {
  16.     now -= tm.tm_gmtoff;
  17.     localtime_r (&now, &tm);
  18.   }
  19.   return ((double) tm.tm_gmtoff) * 1000;
  20. } /* jerry_port_get_local_time_zone_adjustment */
  22. /**
  23.  * Default implementation of jerry_port_get_current_time.
  24.  */
  25. double jerry_port_get_current_time (void)
  26. {
  27.   struct timeval tv;
  29.   if (gettimeofday (&tv, NULL) != 0)
  30.   {
  31.     return 0;
  32.   }
  34.   return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
  35. } /* jerry_port_get_current_time */

External context

  1. #include "jerryscript-port.h"
  2. #include "jerryscript-port-default.h"
  4. /**
  5.  * Pointer to the current context.
  6.  * Note that it is a global variable, and is not a thread safe implementation.
  7.  */
  8. static jerry_context_t *current_context_p = NULL;
  10. /**
  11.  * Set the current_context_p as the passed pointer.
  12.  */
  13. void
  14. jerry_port_default_set_current_context (jerry_context_t *context_p) /**< points to the created context */
  15. {
  16.   current_context_p = context_p;
  17. } /* jerry_port_default_set_current_context */
  19. /**
  20.  * Get the current context.
  21.  *
  22.  * @return the pointer to the current context
  23.  */
  24. jerry_context_t *
  25. jerry_port_get_current_context (void)
  26. {
  27.   return current_context_p;
  28. } /* jerry_port_get_current_context */

Sleep

  1. #include "jerryscript-port.h"
  2. #include "jerryscript-port-default.h"
  4. #ifdef HAVE_TIME_H
  5. #include <time.h>
  6. #elif defined (HAVE_UNISTD_H)
  7. #include <unistd.h>
  8. #endif /* HAVE_TIME_H */
  10. #if defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1)
  11. void jerry_port_sleep (uint32_t sleep_time)
  12. {
  13. #ifdef HAVE_TIME_H
  14.   nanosleep (&(const struct timespec)
  15.   {
  16.     (time_t) sleep_time / 1000, ((long int) sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */
  17.   }
  18.   , NULL);
  19. #elif defined (HAVE_UNISTD_H)
  20.   usleep ((useconds_t) sleep_time * 1000);
  21. #endif /* HAVE_TIME_H */
  22.   (void) sleep_time;
  23. } /* jerry_port_sleep */
  24. #endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */