examples: add pthread-shim in performance-thread sample app
A message that is not in the archive (sent off-list or not yet received): [email protected]
PATCH v4 2/2 examples: add pthread-shim in performance-thread sample app
From: Ian Betts <[email protected]>
This commit adds a simple pthread_shim example for the cooperative scheduler included with this patchset.
The shim demonstrates a way in which legacy code writtem for pthreads could be adapted to lighweight threads.
Signed-off-by Ian Betts <[email protected]>
--- doc/guides/sample_app_ug/performance_thread.rst | 114 ++++ examples/performance-thread/Makefile | 2 + examples/performance-thread/pthread_shim/Makefile | 60 ++ examples/performance-thread/pthread_shim/main.c | 284 ++++++++ .../performance-thread/pthread_shim/pthread_shim.c | 714 +++++++++++++++++++++ .../performance-thread/pthread_shim/pthread_shim.h | 113 ++++ 6 files changed, 1287 insertions(+) create mode 100644 examples/performance-thread/pthread_shim/Makefile create mode 100644 examples/performance-thread/pthread_shim/main.c create mode 100644 examples/performance-thread/pthread_shim/pthread_shim.c create mode 100644 examples/performance-thread/pthread_shim/pthread_shim.h
doc/guides/sample_app_ug/performance_thread.rst +114 -0
@@ -1102,6 +1102,120 @@ it the local data it needs, and pick up the new logical core specific values from pthread local storage at its new home. +.. _pthread_shim: + +Pthread shim +~~~~~~~~~~~~ + +A convenient way to get something working with legacy code can be to use a +shim that adapts pthread API calls to the corresponding L-thread ones. +This approach will not mitigate any of the porting considerations mentioned +in the previous sections, but it will reduce the amount of code churn that +would otherwise been involved. It is a reasonable approach to evaluate +L-threads, before investing effort in porting to the native L-thread APIs. + + +Overview +^^^^^^^^ +The L-thread subsystem includes an example pthread shim. This is a partial +implementation but does contain the API stubs needed to get basic applications +running. There is a simple "hello world" application that demonstrates the +use of the pthread shim. + +A subtlety of working with a shim is that the application will still need +to make use of the genuine pthread library functions, at the very least in +order to create the EAL threads in which the L-thread schedulers will run. +This is the case with DPDK initialization, and exit. + +To deal with the initialization and shutdown scenarios, the shim is capable of +switching on or off its adaptor functionality, an application can control this +behavior by the calling the function ``pt_override_set()``. The default state +is disabled. + +The pthread shim uses the dynamic linker loader and saves the loaded addresses +of the genuine pthread API functions in an internal table, when the shim +functionality is enabled it performs the adaptor function, when disabled it +invokes the genuine pthread function. + +The function ``pthread_exit()`` has additional special handling. The standard +system header file pthread.h declares ``pthread_exit()`` with +``__attribute__((noreturn))`` this is an optimization that is possible because +the pthread is terminating and this enables the compiler to omit the normal +handling of stack and protection of registers since the function is not +expected to return, and in fact the thread is being destroyed. These +optimizations are applied in both the callee and the caller of the +``pthread_exit()`` function. + +In our cooperative scheduling environment this behavior is inadmissible. The +pthread is the L-thread scheduler thread, and, although an L-thread is +terminating, there must be a return to the scheduler in order that the system +can continue to run. Further, returning from a function with attribute +``noreturn`` is invalid and may result in undefined behavior. + +The solution is to redefine the ``pthread_exit`` function with a macro, +causing it to be mapped to a stub function in the shim that does not have the +``noreturn`` attribute. This macro is defined in the file +``pthread_shim.h``. The stub function is otherwise no different than any of +the other stub functions in the shim, and will switch between the real +``pthread_exit()`` function or the ``lthread_exit()`` function as +required. The only difference is that the mapping to the stub by macro +substitution. + +A consequence of this is that the file ``pthread_shim.h`` must be included in +legacy code wishing to make use of the shim. It also means that dynamic +linkage of a pre-compiled binary that did not include pthread_shim.h is not be +supported. + +Given the requirements for porting legacy code outlined in +:ref:`porting_legacy_code_to_run_on_lthreads` most applications will require at +least some minimal adjustment and recompilation to run on L-threads so +pre-compiled binaries are unlikely to be met in practice. + +In summary the shim approach adds some overhead but can be a useful tool to help +establish the feasibility of a code reuse project. It is also a fairly +straightforward task to extend the shim if necessary. + +**Note:** Bearing in mind the preceding discussions about the impact of making +blocking calls then switching the shim in and out on the fly to invoke any +pthread API this might block is something that should typically be avoided. + + +Building and running the pthread shim +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The shim example application is located in the sample application +in the performance-thread folder + +To build and run the pthread shim example + +#. Go to the example applications folder + + .. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + cd ${RTE_SDK}/examples/performance-thread/pthread_shim + + +#. Set the target (a default target is used if not specified). For example: + + .. code-block:: console + + export RTE_TARGET=x86_64-native-linuxapp-gcc + + See the DPDK Getting Started Guide for possible RTE_TARGET values. + +#. Build the application: + + .. code-block:: console + + make + +#. To run the pthread_shim example + + .. code-block:: console + + lthread-pthread-shim -c core_mask -n number_of_channels + .. _lthread_diagnostics: L-thread Diagnostics
examples/performance-thread/Makefile +2 -0
@@ -39,6 +39,8 @@ RTE_TARGET ?= x86_64-native-linuxapp-gcc include $(RTE_SDK)/mk/rte.vars.mk DIRS-$(CONFIG_RTE_PERFORMANCE_THREAD) += l3fwd-thread +DIRS-$(CONFIG_RTE_PERFORMANCE_THREAD) += pthread_shim +
examples/performance-thread/pthread_shim/Makefile new file +60 -0
60 lines not on this page · raw message
examples/performance-thread/pthread_shim/main.c new file +284 -0
284 lines not on this page · raw message
examples/performance-thread/pthread_shim/pthread_shim.c new file +714 -0
714 lines not on this page · raw message
examples/performance-thread/pthread_shim/pthread_shim.h new file +113 -0
113 lines not on this page · raw message
Signature · 1 line
2.1.4