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

```c
/**
 * 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);
```

Error codes

```c
typedef enum
{
  ERR_OUT_OF_MEMORY = 10,
  ERR_SYSCALL = 11,
  ERR_REF_COUNT_LIMIT = 12,
  ERR_FAILED_INTERNAL_ASSERTION = 120
} jerry_fatal_code_t;
```

## I/O

These are the only I/O functions jerry calls.

```c
/**
 * Jerry log levels. The levels are in severity order
 * where the most serious levels come first.
 */
typedef enum
{
  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.
 */
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```

## Date

```c
/**
 * Jerry time zone structure
 */
typedef struct
{
  int offset;                /**< minutes from west */
  int daylight_saving_time;  /**< daylight saving time (1 - DST applies, 0 - not on DST) */
} jerry_time_zone_t;

/**
 * Get timezone and daylight saving data
 *
 * @return true  - if success
 *         false - otherwise
 */
bool jerry_port_get_time_zone (jerry_time_zone_t *);

/**
 * Get system time
 *
 * @return milliseconds since Unix epoch
 */
double jerry_port_get_current_time (void);
```

## External instance

Allow user to provide external buffer for jerry instance (which includes an isolated context and heap with other instances), so that user can config the heap size in runtime and run multiple JS apps simultaneously.

```c
/**
 * Get the current instance, which contains the current context, heap and other infomation.
 * Each port should provide its own implementation of this interface.
 *
 *Note:
 *    This port function will be called automatically by jerry-core
 *    when JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called.
 *
 * @return the pointer to the jerry instance.
 */
struct jerry_instance_t *jerry_port_get_current_instance (void);
```

## Sleep

```c
/**
 * Makes the process sleep for a given time.
 */
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

```c
#include <stdlib.h>
#include "jerryscript-port.h"

/**
 * Default implementation of jerry_port_fatal.
 */
void jerry_port_fatal (jerry_fatal_code_t code)
{
  exit (code);
} /* jerry_port_fatal */
```

## I/O

```c
#include <stdarg.h>
#include "jerryscript-port.h"

/**
 * Provide log message implementation for the engine.
 *
 * Note:
 *      This example ignores the log level.
 */
void
jerry_port_log (jerry_log_level_t level, /**< log level */
                const char *format, /**< format string */
                ...)  /**< parameters */
{
  va_list args;
  va_start (args, format);
  vfprintf (stderr, format, args);
  va_end (args);
} /* jerry_port_log */
```

## Date

```c
#include <sys/time.h>
#include "jerryscript-port.h"

/**
 * Default implementation of jerry_port_get_time_zone.
 */
bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
  struct timeval tv;
  struct timezone tz;

  /* gettimeofday may not fill tz, so zero-initializing */
  tz.tz_minuteswest = 0;
  tz.tz_dsttime = 0;

  if (gettimeofday (&tv, &tz) != 0)
  {
    return false;
  }

  tz_p->offset = tz.tz_minuteswest;
  tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;

  return true;
} /* jerry_port_get_time_zone */

/**
 * Default implementation of jerry_port_get_current_time.
 */
double jerry_port_get_current_time (void)
{
  struct timeval tv;

  if (gettimeofday (&tv, NULL) != 0)
  {
    return 0;
  }

  return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
} /* jerry_port_get_current_time */
```
## External instance

```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"

/**
 * Pointer to the current instance.
 * Note that it is a global variable, and is not a thread safe implementation.
 */
static jerry_instance_t *current_instance_p = NULL;

/**
 * Set the current_instance_p as the passed pointer.
 */
void
jerry_port_default_set_instance (jerry_instance_t *instance_p) /**< points to the created instance */
{
  current_instance_p = instance_p;
} /* jerry_port_default_set_instance */

/**
 * Get the current instance.
 *
 * @return the pointer to the current instance
 */
jerry_instance_t *
jerry_port_get_current_instance (void)
{
  return current_instance_p;
} /* jerry_port_get_current_instance */
```

## Sleep

```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"

#ifdef HAVE_TIME_H
#include <time.h>
#elif defined (HAVE_UNISTD_H)
#include <unistd.h>
#endif /* HAVE_TIME_H */

#ifdef JERRY_DEBUGGER
void jerry_port_sleep (uint32_t sleep_time)
{
#ifdef HAVE_TIME_H
  nanosleep (&(const struct timespec)
  {
    sleep_time / 1000, (sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */
  }
  , NULL);
#elif defined (HAVE_UNISTD_H)
  usleep ((useconds_t) sleep_time * 1000);
#endif /* HAVE_TIME_H */
  (void) sleep_time;
} /* jerry_port_sleep */
#endif /* JERRY_DEBUGGER */
```
