Introduce the Termination Port API

* Moved the error codes to jerry-port.h and declared port function
  `jerry_port_fatal`.

* Moved "exit or abort on fail" functionality to the newly added
  jerry-port-default-fatal.c.

* This implied that a default port-specific API had to be introduced:
  functions `jerry_port_default_set_abort_on_fail` and
  `jerry_port_default_is_abort_on_fail` declared in jerry-port-default.h
  control the fatal exit behaviour.

* For the sake of clarity, renamed jerry-port.c to
  jerry-port-default-io.c.

* Adapted CMakeLists to deal with port implementations consisting of
  more then one source file and exposing headers. This also required
  the renaming of `EXTERNAL_PORT_FILE` cmake option to
  `EXTERNAL_PORT_DIR`.

* Adapted main sources to use the default port header for the
  abort-on-fail functionality, as that is not part of the core jerry
  API anymore.

* Added default port implementation to the static source code checker
  tools.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu

CMakeLists.txt

@@ -132,12 +132,11 @@ project (Jerry C ASM)
  endif()
 
 
- # Should we use external jerry-port.c?
+ # Should we use external port?
- if(DEFINED EXTERNAL_PORT_FILE AND NOT EXTERNAL_PORT_FILE STREQUAL "UNDEFINED")
+ if(DEFINED EXTERNAL_PORT_DIR AND NOT EXTERNAL_PORT_DIR STREQUAL "UNDEFINED")
-   set(SOURCE_PORT_IMPLEMENTATION ${EXTERNAL_PORT_FILE})
+   set(PORT_DIR ${EXTERNAL_PORT_DIR})
-   set(USE_DEFAULT_PORT FALSE)
  else()
-   set(USE_DEFAULT_PORT TRUE)
+   set(PORT_DIR ${CMAKE_SOURCE_DIR}/targets/default)
  endif()
 
 # Are there any interfaces for external libraries, other than libc, that should be registered?
@@ -420,6 +419,7 @@ endif()
                  PROPERTY LINK_FLAGS "${COMPILE_FLAGS_JERRY} ${FLAGS_COMMON_${BUILD_MODE}} ${LINKER_FLAGS_COMMON} ${LINKER_FLAGS_STATIC}")
     target_compile_definitions(${TARGET_NAME} PRIVATE ${DEFINES_JERRY})
     target_include_directories(${TARGET_NAME} PRIVATE ${INCLUDE_CORE_INTERFACE})
+    target_include_directories(${TARGET_NAME} PRIVATE ${PORT_DIR})
     target_include_directories(${TARGET_NAME} SYSTEM PRIVATE ${INCLUDE_LIBC_INTERFACE})
     target_include_directories(${TARGET_NAME} SYSTEM PRIVATE ${INCLUDE_EXTERNAL_LIBS_INTERFACE})
     if(("${PLATFORM}" STREQUAL "DARWIN") AND (NOT (CMAKE_COMPILER_IS_GNUCC)))

jerry-core/CMakeLists.txt

@@ -148,11 +148,7 @@ project (JerryCore C ASM)
       ${SOURCE_CORE_JRT})
 
  # Jerry port
- if(USE_DEFAULT_PORT)
+ file(GLOB SOURCE_PORT_FILES ${PORT_DIR}/*.c)
-   file(GLOB SOURCE_PORT_FILES ${CMAKE_SOURCE_DIR}/targets/default/*.c)
- else()
-   set(SOURCE_PORT_FILES ${SOURCE_PORT_IMPLEMENTATION})
- endif()
 
  # All-in-one build
  if("${ENABLE_ALL_IN_ONE}" STREQUAL "ON")

jerry-core/jerry-internal.h

@@ -29,7 +29,4 @@ jerry_dispatch_external_function (ecma_object_t *, ecma_external_pointer_t, ecma
 extern void
 jerry_dispatch_object_free_callback (ecma_external_pointer_t, ecma_external_pointer_t);
 
-extern bool
-jerry_is_abort_on_fail (void);
-
 #endif /* !JERRY_INTERNAL_H */

jerry-core/jerry-port.h

@@ -35,6 +35,42 @@ int jerry_port_logmsg (FILE *stream, const char *format, ...);
 int jerry_port_errormsg (const char *format, ...);
 int jerry_port_putchar (int c);
 
+/*
+ * Termination Port API
+ *
+ * Note:
+ *      It is questionable whether a library should be able to terminate an
+ *      application. However, as of now, we only have the concept of completion
+ *      code around jerry_parse and jerry_run. Most of the other API functions
+ *      have no way of signaling an error. So, we keep the termination approach
+ *      with this port function.
+ */
+
+/**
+ * Error codes
+ */
+typedef enum
+{
+  ERR_OUT_OF_MEMORY = 10,
+  ERR_SYSCALL = 11,
+  ERR_REF_COUNT_LIMIT = 12,
+  ERR_UNIMPLEMENTED_CASE = 118,
+  ERR_FAILED_INTERNAL_ASSERTION = 120
+} jerry_fatal_code_t;
+
+/**
+ * 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);
+
 /**
  * @}
  */

jerry-core/jerry.c

@@ -1689,18 +1689,6 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, /**< [out] Jerry's ma
   *out_stack_limit_p = CONFIG_MEM_STACK_LIMIT;
 } /* jerry_get_memory_limits */
 
-/**
- * Check whether 'abort' should be called instead of 'exit' upon exiting with non-zero exit code.
- *
- * @return true - if 'abort on fail' flag is set,
- *         false - otherwise.
- */
-bool
-jerry_is_abort_on_fail (void)
-{
-  return ((jerry_flags & JERRY_FLAG_ABORT_ON_FAIL) != 0);
-} /* jerry_is_abort_on_fail */
-
 /**
  * Parse script for specified context
  *

jerry-core/jerry.h

@@ -44,21 +44,8 @@ typedef enum
   JERRY_FLAG_PARSE_ONLY         = (1u << 3), /**< parse only, prevents script execution (only for testing)
                                               *   TODO: Remove. */
   JERRY_FLAG_ENABLE_LOG         = (1u << 4), /**< enable logging */
-  JERRY_FLAG_ABORT_ON_FAIL      = (1u << 5), /**< abort instead of exit in case of failure */
 } jerry_flag_t;
 
-/**
- * Error codes
- */
-typedef enum
-{
-  ERR_OUT_OF_MEMORY = 10,
-  ERR_SYSCALL = 11,
-  ERR_REF_COUNT_LIMIT = 12,
-  ERR_UNIMPLEMENTED_CASE = 118,
-  ERR_FAILED_INTERNAL_ASSERTION = 120
-} jerry_fatal_code_t;
-
 /**
  * Jerry engine build date
  */

jerry-core/jrt/jrt-fatals.c

@@ -65,16 +65,7 @@ jerry_fatal (jerry_fatal_code_t code) /**< status code */
   }
 #endif /* !JERRY_NDEBUG */
 
-  if (code != 0
+  jerry_port_fatal (code);
-      && code != ERR_OUT_OF_MEMORY
-      && jerry_is_abort_on_fail ())
-  {
-    abort ();
-  }
-  else
-  {
-    exit (code);
-  }
 
   /* to make compiler happy for some RTOS: 'control reaches end of non-void function' */
   while (true)

main-unix.c

@@ -20,6 +20,7 @@
 
 #include "jerry.h"
 #include "jerry-port.h"
+#include "jerry-port-default.h"
 
 /**
  * Maximum command line arguments number
@@ -358,7 +359,7 @@ main (int argc,
     }
     else if (!strcmp ("--abort-on-fail", argv[i]))
     {
-      flags |= JERRY_FLAG_ABORT_ON_FAIL;
+      jerry_port_default_set_abort_on_fail (true);
     }
     else if (!strncmp ("-", argv[i], 1))
     {

targets/default/jerry-port-default-fatal.c

@@ -0,0 +1,60 @@
+/* Copyright 2016 Samsung Electronics Co., Ltd.
+ * Copyright 2016 University of Szeged
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <stdlib.h>
+
+#include "jerry-port.h"
+#include "jerry-port-default.h"
+
+static bool abort_on_fail = false;
+
+/**
+ * Sets whether 'abort' should be called instead of 'exit' upon exiting with
+ * non-zero exit code in the default implementation of jerry_port_fatal.
+ */
+void jerry_port_default_set_abort_on_fail (bool flag) /**< new value of 'abort on fail' flag */
+{
+  abort_on_fail = flag;
+} /* jerry_port_default_set_abort_on_fail */
+
+/**
+ * Check whether 'abort' should be called instead of 'exit' upon exiting with
+ * non-zero exit code in the default implementation of jerry_port_fatal.
+ *
+ * @return true - if 'abort on fail' flag is set,
+ *         false - otherwise.
+ */
+bool jerry_port_default_is_abort_on_fail ()
+{
+  return abort_on_fail;
+} /* jerry_port_default_is_abort_on_fail */
+
+/**
+ * Default implementation of jerry_port_fatal.
+ */
+void jerry_port_fatal (jerry_fatal_code_t code)
+{
+  if (code != 0
+      && code != ERR_OUT_OF_MEMORY
+      && jerry_port_default_is_abort_on_fail ())
+  {
+    abort ();
+  }
+  else
+  {
+    exit (code);
+  }
+} /* jerry_port_fatal */

targets/default/jerry-port-default-io.c

@@ -13,9 +13,10 @@
  * limitations under the License.
  */
 
-#include "jerry-port.h"
 #include <stdarg.h>
 
+#include "jerry-port.h"
+
 /**
  * Provide log message to filestream implementation for the engine.
  */

targets/default/jerry-port-default.h

@@ -0,0 +1,42 @@
+/* Copyright 2016 Samsung Electronics Co., Ltd.
+ * Copyright 2016 University of Szeged
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef JERRY_PORT_DEFAULT_H
+#define JERRY_PORT_DEFAULT_H
+
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* __cplusplus */
+
+/** \addtogroup jerry_port_default Default Jerry engine port API
+ * These functions are only available if the default port of Jerry is used.
+ * @{
+ */
+
+void jerry_port_default_set_abort_on_fail (bool);
+bool jerry_port_default_is_abort_on_fail (void);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+#endif /* !JERRY_PORT_DEFAULT_H */

targets/nuttx-stm32f4/main-nuttx.c

@@ -19,6 +19,7 @@
 
 #include "jerry.h"
 #include "jerry-port.h"
+#include "jerry-port-default.h"
 
 /**
  * The module interface routine
@@ -199,7 +200,7 @@ int jerryscript_entry (int argc, char *argv[])
     }
     else if (!strcmp ("--abort-on-fail", argv[i]))
     {
-      flags |= JERRY_FLAG_ABORT_ON_FAIL;
+      jerry_port_default_set_abort_on_fail (true);
     }
     else if (!strcmp ("--log-level", argv[i]))
     {

tools/check-cppcheck.sh

@@ -24,11 +24,12 @@ else
 fi
 
 JERRY_CORE_DIRS=`find jerry-core -type d`
+JERRY_PORT_DEFAULT_DIRS=`find targets/default -type d`
 JERRY_LIBC_DIRS=`find jerry-libc -type d`
 JERRY_LIBM_DIRS=`find jerry-libm -type d`
 
 INCLUDE_DIRS=()
-for DIR in $JERRY_CORE_DIRS $JERRY_LIBC_DIRS $JERRY_LIBM_DIRS
+for DIR in $JERRY_CORE_DIRS $JERRY_PORT_DEFAULT_DIRS $JERRY_LIBC_DIRS $JERRY_LIBM_DIRS
 do
  INCLUDE_DIRS=("${INCLUDE_DIRS[@]}" "-I$DIR")
 done
@@ -39,4 +40,4 @@ cppcheck -j$CPPCHECK_JOBS --force \
  --error-exitcode=1 \
  --exitcode-suppressions=tools/cppcheck/suppressions-list \
  "${INCLUDE_DIRS[@]}" \
- jerry-core jerry-libc jerry-libm *.c *h tests/unit
+ jerry-core targets/default jerry-libc jerry-libm *.c *h tests/unit

tools/check-vera.sh

@@ -16,6 +16,7 @@
 # limitations under the License.
 
 JERRY_CORE_FILES=`find ./jerry-core -name "*.c" -or -name "*.h"`
+JERRY_PORT_DEFAULT_FILES=`find ./targets/default -name "*.c" -or -name "*.h"`
 JERRY_LIBC_FILES=`find ./jerry-libc -name "*.c" -or -name "*.h"`
 JERRY_LIBM_FILES=`find ./jerry-libm -name "*.c" -or -name "*.h"`
 JERRY_MAIN_FILES=`find . -maxdepth 1 -name "*.c" -or -name "*.h"`
@@ -23,4 +24,4 @@ UNIT_TEST_FILES=`find ./tests/unit -name "*.c" -or -name "*.h"`
 
 vera++ -r tools/vera++ -p jerry \
  -e --no-duplicate \
- $JERRY_CORE_FILES $JERRY_LIBC_FILES $JERRY_LIBM_FILES $JERRY_MAIN_FILES $UNIT_TEST_FILES
+ $JERRY_CORE_FILES $JERRY_PORT_DEFAULT_FILES $JERRY_LIBC_FILES $JERRY_LIBM_FILES $JERRY_MAIN_FILES $UNIT_TEST_FILES