Event Machine (EM) on ODP v3.6.0

See changes in CHANGE_NOTES, README and include/event_machine/README_API

Author: cawallen

.github/workflows/ci-pipeline.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout EM-ODP
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           # Full git history is needed to get a proper list of changed files
           # within `super-linter`
@@ -35,7 +35,7 @@ jobs:
   Build-Doxygen:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -62,7 +62,7 @@ jobs:
         sudo apt-get install libcli-dev
         sudo apt-get install telnet
     - name: Checkout EM-ODP
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Build EM-ODP
       run: ./scripts/build.sh
     - name: Run Robot Tests
@@ -74,7 +74,7 @@ jobs:
   Cross-Compile-for-arm64:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Cross-compile EM-ODP for arm64
       run: >
           sudo docker run

.github/workflows/gh-pages.yml

@@ -14,7 +14,7 @@ jobs:
   Documentation:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update

CHANGE_NOTES

@@ -52,6 +52,78 @@ Examples:
 - See em-odp/README for usage and compilation instructions.
 - See em-odp/include/event_machine/README_API for API changes
 
+--------------------------------------------------------------------------------
+Event Machine (EM) on ODP v3.6.0
+--------------------------------------------------------------------------------
+- Support for EM API v3.6 (em-odp/include/),
+  see API additions and changes in em-odp/include/event_machine/README_API.
+  Summary:
+  * Packet event APIs: new API module for manipulation of packet events
+  * Timer API: moved from add-ons to the base EM API
+  * Event: em_event_pointer_and_size()
+  * Deprecation macros/defines
+
+- Add support for using ODP API 1.45
+  Update EM to be able to run against ODP API v1.45.
+
+- Deprecated EM API enable/disable configuration option
+ - Add a new configure-script option that enables/disables decprecated EM APIs.
+   Old EM APIs can be deprecated in new EM releases through the use of
+   deprecation macros and defines found in event_machine_deprecated.h(.in)
+   (additionally see include/event_machine/README_API for API v3.6 description
+    of deprecation macros).
+   The deprecation of an API will cause any use of it to fail the compilation.
+   The user may, however, decide to enable the deprecated APIs (by using
+   --enable-deprecated) during a transition period until the deprecated API
+   usage has been replaced.
+
+   configure.ac:
+   -------------
+   New configure option:
+   --enable-deprecated  enable deprecated EM API definitions [default=disabled]
+
+- Event State Verification (ESV) changes
+ - Added ESV compile-time vs. runtime configuration checks.
+   Verifies that ESV was activated also during
+   compile time (with configure option: '--enable_esv')
+   when enabling it during runtime (via the EM config file: esv.enable = true).
+   Warn the user otherwise.
+   The user might not notice that the run time config file option has no effect
+   if ESV has been disabled during compilation.
+   Example:
+        build> ../configure --disable-esv …  (set the define EM_ESV_ENABLE to 0)
+          vs.
+        <em-odp>/config/em-odp.conf:
+            esv: {
+                    # Runtime ESV enable/disable option.
+                    # Allows the user to disable ESV without recompilation when
+                    # 'configure --enable-esv'.
+                    enable = true
+                    …
+            }
+        will show the following warning at startup:
+        …
+        EM ESV config: (EM_ESV_ENABLE=0)
+          ESV disabled
+          esv.enable: true(1)
+          WARNING: ESV disabled (build-time) - config file option IGNORED!
+        …
+   Note that the warning is only printed, no other action is taken.
+
+- EM Termination
+ - Move functionality from em_term_core() to em_term().
+   Now em_term_core() only flushes events stashed locally on the core
+   and em_term() flushes the rest of the events at the end.
+   Additionally, em_term() joins all available queue groups to be able to
+   flush all events from the scheduler before terminating.
+
+- Programs
+ - New performance test programs added
+   - programs/performance/queues_output.c
+     Event Machine performance test for output queues.
+   - programs/performance/loop_vectors.c
+     Event Machine performance test for vector events
+
 --------------------------------------------------------------------------------
 Event Machine (EM) on ODP v3.5.0
 --------------------------------------------------------------------------------
@@ -556,7 +628,7 @@ Event Machine (EM) on ODP v2.9.0
 - EM Command Line Interface (EM CLI) update
   - Further EM CLI commands added, use the command "help" to see all available
     commands:
-	(<em-odp.conf>: cli.enable = true)
+        (<em-odp.conf>: cli.enable = true)
         $> telnet localhost 55555
         EM-ODP> help
         Commands available:
@@ -621,7 +693,7 @@ Event Machine (EM) on ODP v2.8.0
     em_eo_start_sync(), em_queue_group_modify_sync() etc. are allowed.
     Previously only one sync-operation at a time was permitted, now there is
     no limit.
-    One restriction remains: conserned cores need to be dispatching
+    One restriction remains: concerned cores need to be dispatching
     (or processing other sync-API calls) for the operations to complete.
     A core that has left the dispatch loop or is sleeping etc. will not allow
     the sync-API operation to complete.
@@ -879,10 +951,10 @@ Event Machine on ODP v2.5.0
    "
   Note: ESV-errors are always reported with the same error-code:​
         EM_FATAL(EM_ERR_EVENT_STATE) = 0x80000010​
-	'prev-state' shows the previous good state of the event. i.e. the
-	previous place where EM observed the event in a valid state.
-	'new-state' shows the current detected illegal state that
-	caused the error.
+        'prev-state' shows the previous good state of the event. i.e. the
+        previous place where EM observed the event in a valid state.
+        'new-state' shows the current detected illegal state that
+        caused the error.
 
   Using ESV has an impact on performance.
   Each event-state transition updates an atomic counter and stores further
@@ -1158,9 +1230,10 @@ Event Machine on ODP v1.3.0
 --------------------------------------------------------------------------------
 - Support for EM API v1.3 (em-odp/include), see API changes in
   em-odp/include/event_machine/README_API
-- Support for EM add-ons APIs, here the EM event timer API v1.0, read about
-  add-on APIs in em-odp/include/event_machine/add-ons/README.
-  See new event timer examples/tests in em-odp/programs/example/add-ons/
+- Support for EM add-ons APIs, read about add-on APIs in
+  em-odp/include/event_machine/add-ons/README.
+- EM event timer API v1.0.
+  See new event timer examples/tests in em-odp/programs/example/timer/
 
 --------------------------------------------------------------------------------
 Event Machine on ODP v1.2.3

README

@@ -120,10 +120,6 @@ Usually EM work better with the following config changes:
     outside of EM can't be tracked, thus disable this.
       sched_basic.order_stash_size = 512 -> 0
 
-- Stash: Disable strict stash size.
-  Rely on stash 'put' return value to determine operation status.
-     stash.strict_size = 1 -> 0
-
 ===============================================================================
 CPU Architecture specific options
 ===============================================================================

configure.ac

@@ -3,7 +3,7 @@ AC_PREREQ([2.69])
 # Version
 ############################
 m4_define([em_version_api_major], [3])
-m4_define([em_version_api_minor], [5])
+m4_define([em_version_api_minor], [6])
 m4_define([em_version_implementation], [0])
 m4_define([em_version_fix], [0])
 
@@ -169,6 +169,7 @@ EM_CHECK_CFLAG([-Wformat-security])
 EM_CHECK_CFLAG([-Wundef])
 EM_CHECK_CFLAG([-Wwrite-strings])
 EM_CHECK_CFLAG([-Wno-vla]) # Allow variable-length arrays (vla), for clang.
+EM_CHECK_CFLAG([-Wshadow=local])
 
 # GCC 10,11 sometimes gets confused about object sizes and gives bogus warnings.
 # Make the affected warnings generate only warnings, not errors.
@@ -298,6 +299,20 @@ AC_ARG_ENABLE([debug-print],
 # Substitute @EM_DEBUG_PRINT@ into the pkgconfig file libemodp.pc.in
 AC_SUBST([EM_DEBUG_PRINT])
 
+##########################################################################
+# Enable/disable deprecated API definitions
+##########################################################################
+EM_DEPRECATED_API=0
+deprecated=no
+AC_ARG_ENABLE([deprecated],
+    [AS_HELP_STRING([--enable-deprecated],
+		    [enable deprecated API definitions [default=disabled]])],
+    [if test "x$enableval" = "xyes"; then
+	EM_DEPRECATED_API=1
+	deprecated=yes
+    fi])
+AC_SUBST(EM_DEPRECATED_API)
+
 #########################################################################
 # Override EM-define value 'EM_DEBUG_TIMESTAMP_ENABLE' to 0...2
 # --enable-debug-timestamps=0...2   Set 'EM_DEBUG_TIMESTAMP_ENABLE' to the given
@@ -459,7 +474,7 @@ AC_CONFIG_FILES([
 	programs/common/Makefile
 	programs/example/Makefile
 	programs/example/hello/Makefile
-	programs/example/add-ons/Makefile
+	programs/example/timer/Makefile
 	programs/example/api-hooks/Makefile
 	programs/example/dispatcher/Makefile
 	programs/example/error/Makefile
@@ -474,6 +489,7 @@ AC_CONFIG_FILES([
 
 AC_CONFIG_FILES([
 	include/event_machine/api/event_machine_version.h
+	include/event_machine/api/event_machine_deprecated.h
 	])
 
 ##########################################################################
@@ -641,7 +657,10 @@ AS_IF([test "x$enable_doxygen" != "xno"],
       [DX_HTML_FEATURE(ON)
        DX_PDF_FEATURE(OFF)
        DX_PS_FEATURE(OFF)
-       DX_INIT_DOXYGEN($PACKAGE_NAME, ${srcdir}/doc/Doxyfile, ${builddir}/doc/event_machine_api)
+       DX_DOT_FEATURE(ON)
+       DX_INIT_DOXYGEN($PACKAGE_NAME,
+                       ${srcdir}/doc/Doxyfile,
+                       ${builddir}/doc/event_machine_api)
        AM_COND_IF([HAVE_DOXYGEN], [AC_CONFIG_FILES([doc/Makefile])])
       ])
 
@@ -704,6 +723,7 @@ AC_MSG_RESULT([
 	example programs:	${with_programs}
 	example static linkage:	${enable_static_applications}
 	default config-file:	${default_config_file}
+	deprecated APIs:	${deprecated}
 
 	EM Compile Time Options
 	=======================

doc/Doxyfile

@@ -2359,7 +2359,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: YES.
 
-HAVE_DOT               = YES
+HAVE_DOT               = $(HAVE_DOT)
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of