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;
  12. /**
  13. * Display or log a debug/error message, and sends it to the debugger client as well.
  14. * The function should implement a printf-like interface, where the first argument
  15. * specifies the log level and the second argument specifies a format string on how
  16. * to stringify the rest of the parameter list.
  17. *
  18. * This function is only called with messages coming from the jerry engine as
  19. * the result of some abnormal operation or describing its internal operations
  20. * (e.g., data structure dumps or tracing info).
  21. *
  22. * It should be the port that decides whether error and debug messages are logged to
  23. * the console, or saved to a database or to a file.
  24. *
  25. * Example: a libc-based port may implement this with vfprintf(stderr) or
  26. * vfprintf(logfile), or both, depending on log level.
  27. *
  28. * Note:
  29. * This port function is called by jerry-core when JERRY_LOGGING is
  30. * enabled. It is also common practice though to use this function in
  31. * application code.
  32. */
  33. 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 */
  12. /**
  13. * Release the previously opened file's content.
  14. */
  15. void
  16. jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
  17. {
  18. free (buffer_p);
  19. } /* jerry_port_release_source */
  20. /**
  21. * Normalize a file path
  22. *
  23. * @return length of the path written to the output buffer
  24. */
  25. size_t
  26. jerry_port_normalize_path (const char *in_path_p, /**< input file path */
  27. char *out_buf_p, /**< output buffer */
  28. size_t out_buf_size, /**< size of output buffer */
  29. char *base_file_p) /**< base file path */
  30. {
  31. // normalize in_path_p by expanding relative paths etc.
  32. // if base_file_p is not NULL, in_path_p is relative to that file
  33. // write to out_buf_p the normalized path
  34. // return length of written path
  35. } /* jerry_port_normalize_path */
  36. /**
  37. * Get the module object of a native module.
  38. *
  39. * Note:
  40. * This port function is called by jerry-core when ES2015_MODULE_SYSTEM
  41. * is enabled.
  42. *
  43. * @param name String value of the module specifier.
  44. *
  45. * @return Undefined, if 'name' is not a native module
  46. * jerry_value_t containing the module object, otherwise
  47. */
  48. jerry_value_t
  49. jerry_port_get_native_module (jerry_value_t name) /**< module specifier */
  50. {
  51. (void) name;
  52. return jerry_create_undefined ();
  53. }

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);
  33. /**
  34. * Get system time
  35. *
  36. * Note:
  37. * This port function is called by jerry-core when
  38. * JERRY_BUILTIN_DATE is set to 1. It is also common practice
  39. * in application code to use this function for the initialization of the
  40. * random number generator.
  41. *
  42. * @return milliseconds since Unix epoch
  43. */
  44. 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"
  3. /**
  4. * Default implementation of jerry_port_fatal.
  5. */
  6. void jerry_port_fatal (jerry_fatal_code_t code)
  7. {
  8. exit (code);
  9. } /* jerry_port_fatal */

I/O

  1. #include <stdarg.h>
  2. #include "jerryscript-port.h"
  3. /**
  4. * Provide log message implementation for the engine.
  5. *
  6. * Note:
  7. * This example ignores the log level.
  8. */
  9. void
  10. jerry_port_log (jerry_log_level_t level, /**< log level */
  11. const char *format, /**< format string */
  12. ...) /**< parameters */
  13. {
  14. va_list args;
  15. va_start (args, format);
  16. vfprintf (stderr, format, args);
  17. va_end (args);
  18. } /* 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"
  4. /**
  5. * Default implementation of jerry_port_get_local_time_zone_adjustment.
  6. */
  7. double jerry_port_get_local_time_zone_adjustment (double unix_ms, /**< ms since unix epoch */
  8. bool is_utc) /**< is the time above in UTC? */
  9. {
  10. struct tm tm;
  11. time_t now = (time_t) (unix_ms / 1000);
  12. localtime_r (&now, &tm);
  13. if (!is_utc)
  14. {
  15. now -= tm.tm_gmtoff;
  16. localtime_r (&now, &tm);
  17. }
  18. return ((double) tm.tm_gmtoff) * 1000;
  19. } /* jerry_port_get_local_time_zone_adjustment */
  20. /**
  21. * Default implementation of jerry_port_get_current_time.
  22. */
  23. double jerry_port_get_current_time (void)
  24. {
  25. struct timeval tv;
  26. if (gettimeofday (&tv, NULL) != 0)
  27. {
  28. return 0;
  29. }
  30. return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
  31. } /* jerry_port_get_current_time */

External context

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

Sleep

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