Jerry API: throwing exception

[ILyoan]

It seems like there's no api for supporting exception handling in Jerry API.

We need exception handling api that facilitates following use case:

• Creating error object
• Throwing an error.

And below is probably less significant.

• Creating try-catch block. See Exception API on v8 for more understanding.

[ruben-ayrapetyan]

@ILyoan ,
Using current API version, we could throw an exception from natively implemented functions:

/**
 * Dispatch call to specified external function using the native handler
 *
 * Note:
 *       if called native handler returns true, then dispatcher just returns value received
 *       through 'return value' output argument, otherwise - throws the value as an exception.

Also, we could check if unhandled exception was thrown during execution of function called through API, by looking at return value of jerry_api_call_function / jerry_api_construct_object:

/**
 * Call function specified by a function object
 *
 * Note:
 *      if call was performed successfully, returned value should be freed
 *      with jerry_api_release_value just when the value becomes unnecessary.
 *
 * @return true, if call was performed successfully, i.e.:
 *                - specified object is a function object (see also jerry_api_is_function);
 *                - no unhandled exceptions were thrown in connection with the call;
 *         false - otherwise.
 */

Unhandled exception thrown during execution of main code called by jerry_run, is indicated with the interface's return value: JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION.


Currently, there is no interface for creating specific Error objects in API.

We could add the interface, implementing it using ecma_new_standard_error internal API,
and creating externally visible enumeration with types of Error objects that could be instantiated using API.

[ILyoan]

@ruben-ayrapetyan Thanks for the claim.
In this case, adding an api for creating error object is sufficient to resolve this issue.

I think API like below is suitable

typedef enum
{
  JERRY_ERROR_COMMON, /**< Error */
  JERRY_ERROR_EVAL, /**< EvalError */
  JERRY_ERROR_RANGE, /**< RangeError */
  JERRY_ERROR_REFERENCE, /**< ReferenceError */
  JERRY_ERROR_SYNTAX, /**< SyntaxError */
  JERRY_ERROR_TYPE, /**< TypeError */
  JERRY_ERROR_URI /**< URIError */
} jerry_error_t;

jerry_api_object_t* jerry_api_create_error(jerry_error_t error_type, const char* message);

Some entry in jerry_error_t could be removed if there is no use case, or just retaining it is also ok.

Any opinion?

[sand1k]

@ILyoan, @egavrin It seems that these error types:

typedef enum
{
  JERRY_ERROR_COMMON, /**< Error */
  JERRY_ERROR_EVAL, /**< EvalError */
  JERRY_ERROR_RANGE, /**< RangeError */
  JERRY_ERROR_REFERENCE, /**< ReferenceError */
  JERRY_ERROR_SYNTAX, /**< SyntaxError */
  JERRY_ERROR_TYPE, /**< TypeError */
  JERRY_ERROR_URI /**< URIError */
} jerry_error_t;

could only be thrown by the engine internally, and there is no need to create such exceptions using the API (they are always created by the core of the engine).

Could you, please, give an example when it is needed to throw an exception using the API?

I consider two possible ways of implementing jerry_api_create_error:

• All API exceptions use JERRY_ERROR_COMMON type (or any other, but only one type for all API exceptions), so that jerry_api_create_error doesn't require error_type parameter at all
• API exceptions should use completely different enum for error types, so that we introduce jerry_api_error_t enum which doesn't duplicate jerry_error_t

[ILyoan]

@sand1k Javascript application programs are also able to create and throw such exceptions, for example:

if (typeof arg1 === 'String') {
  throw new TypeError('The first argument should type of String');
}

if (isNaN(parseInt(age)) {
  throw new SyntaxError("Please enter a valid age");
}
else if (age < 13) {
  throw new RangeError("Sorry, but you are too young for this movie");
}

And IoT.js is much likely to throw such exceptions since it deals with I/O(files, pipes, networks, and etc), for example:

if ((err = open(path, flags, mode) < 0)) {
  // file open failed
  // throw new Error(<error message>);
  const char* str_err = strerr(err);
  jerry_api_string_t* jstr_error_p = jerry_api_create_string(str_err); 
  jerry_api_object_t* jerror_p = jerry_api_create_error(JERRY_ERROR_COMMON, jstr_error_p);
  ret_val_p->type = JERRY_API_DATA_TYPE_OBJECT;
  ret_val_p->v_object = jerror_p;
  jerry_api_release_string(jstr_error_p);
  // returning false results in throwing the return value.
  return false; 
}

I think api jerry_api_create_error for creating Error object could take error type. and I couldn't see why we need to restrict the entry of the jerry_api_error_t.
IoT.js could create and throw Error, TypeError, RangeError, ReferenceError, and URIError according to its API. and not sure if there is no use case for EvalError and SyntaxError.

[ILyoan]

It's quite quiet here :).
Could we go with the first PR then ?

[sand1k]

Eventually, separate enum seems to be better than the rest options. And I suppose we don't need EvalError and UriError in it.
@egavrin, what do you think?

[egavrin]

Ok, let's rollback to the original PR then. We may revise API later.
/cc @ILyoan @sand1k

[ILyoan]

Closing as #76 landed.