From 8ebd3230a1d64bab14042333680696532b678d3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20G=C3=A1l?= Date: Wed, 31 Jul 2019 19:23:55 +0200 Subject: [PATCH] Make sure that snapshot API return values are the same as in the docs (#2997) The snapshot API docs describe that those functions returns error if the related features are not enabled. Updated the return values to follow the API documentation. JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com --- docs/02.API-REFERENCE.md | 63 +++++++++++++++++++++++++-------- jerry-core/api/jerry-snapshot.c | 8 ++--- 2 files changed, 52 insertions(+), 19 deletions(-) diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index f01473d4..5fbd8407 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -6505,8 +6505,12 @@ main (void) Generate snapshot from the specified source code. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6560,7 +6564,11 @@ main (void) global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + if (!jerry_value_is_error (generate_result)) + { + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + } + jerry_release_value (generate_result); jerry_cleanup (); @@ -6586,8 +6594,12 @@ with the given arguments. The function arguments and function body are passed as separated arguments. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6648,7 +6660,11 @@ main (void) func_snapshot_buffer, sizeof (func_snapshot_buffer) / sizeof (uint32_t)); - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + if (!jerry_value_is_error (generate_result)) + { + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + } + jerry_release_value (generate_result); jerry_cleanup (); @@ -6670,8 +6686,12 @@ main (void) Execute snapshot from the specified buffer. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_SNAPSHOT_EXEC`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6683,13 +6703,13 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, uint32_t exec_snapshot_opts); ``` -- `snapshot_p` - pointer to snapshot -- `snapshot_size` - size of snapshot in bytes -- `func_index` - index of executed function +- `snapshot_p` - pointer to snapshot. +- `snapshot_size` - size of snapshot in bytes. +- `func_index` - index of executed function. - `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags. - return value - - result of bytecode, if run was successful - - thrown error, otherwise + - result of bytecode, if run was successful. + - thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled). *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. @@ -6716,6 +6736,7 @@ main (void) 0, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + // generate_result should be checked if it is an error or not size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result); jerry_release_value (generate_result); @@ -6728,6 +6749,9 @@ main (void) global_mode_snapshot_size, 0, 0); + + // check the `res` value for error and process the result. + jerry_release_value (res); jerry_cleanup (); @@ -6750,8 +6774,12 @@ Load the selected snapshot function from the specified buffer as a function obje The lexical environment of the loaded function is always the global lexical environment. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_SNAPSHOT_EXEC`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6846,6 +6874,11 @@ main (void) Collect the used literals from the given snapshot and save them into a buffer in list or C format. None of these literals are magic strings. In C format only valid identifiers are collected. +*Note*: +- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return zero. + **Prototype** ```c diff --git a/jerry-core/api/jerry-snapshot.c b/jerry-core/api/jerry-snapshot.c index df3b3d8d..e848710f 100644 --- a/jerry-core/api/jerry-snapshot.c +++ b/jerry-core/api/jerry-snapshot.c @@ -881,7 +881,7 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p, /**< script resour JERRY_UNUSED (buffer_p); JERRY_UNUSED (buffer_size); - return 0; + return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot save is not supported."); #endif /* ENABLED (JERRY_SNAPSHOT_SAVE) */ } /* jerry_generate_snapshot */ @@ -1032,7 +1032,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */ JERRY_UNUSED (func_index); JERRY_UNUSED (exec_snapshot_opts); - return ECMA_VALUE_FALSE; + return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot execution is not supported."); #endif /* ENABLED (JERRY_SNAPSHOT_EXEC) */ } /* jerry_exec_snapshot */ @@ -1831,7 +1831,7 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, /**< scri JERRY_UNUSED (buffer_p); JERRY_UNUSED (buffer_size); - return 0; + return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot save is not supported."); #endif /* ENABLED (JERRY_SNAPSHOT_SAVE) */ } /* jerry_generate_function_snapshot */ @@ -1858,6 +1858,6 @@ jerry_load_function_snapshot (const uint32_t *function_snapshot_p, /**< snapshot JERRY_UNUSED (func_index); JERRY_UNUSED (exec_snapshot_opts); - return ECMA_VALUE_FALSE; + return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot execution is not supported."); #endif /* ENABLED (JERRY_SNAPSHOT_EXEC) */ } /* jerry_load_function_snapshot */ -- GitLab