Zth (libzth)
Loading...
Searching...
No Matches
Zth (libzth)

CI

Zth (libzth) - Zeta threads

This library provides user-space cooperative multitasking, also known as fibers. One can see fibers as threads, but with the exception that you explicitly have to indicate when the fiber is allowed to switch to another fiber. As a result, locking, synchronization, using shared data structures between fibers is way easier than when using threads. See also https://en.wikipedia.org/wiki/Fiber_(computer_science).

The main benefits of Zth are:

  • Cross-platform (Linux/Windows/macOS/bare metal) library for cross-platform application development.
  • No dependencies, other than a C library (usually newlib for embedded targets), and clock_gettime(). When available, ZeroMQ is supported and made fiber-aware, which can be used for inter-thread or inter-process communication.
  • The configuration can be tailored towards your target, such as fiber stack size, time slices, debug/VCD output.
  • Usage of dynamic memory is minimized (only during fiber creation and cleanup), and it allocator-aware.
  • Support for ASan, LSan, UBSan, and Valgrind.

Working with fibers is very easy. The examples/1_helloworld example starts two fibers by using zth::fiber():

#include <zth>
#include <cstdio>
void world()
{
printf("Wonderful\n");
zth::yield();
printf("World!!1\n");
}
void hello()
{
zth::fiber(world);
printf("Hello\n");
}
int main_fiber(int argc, char** argv)
{
zth::fiber(hello);
return 0;
}
main_fiber
int main_fiber(int argc, char **argv)
Definition main.cpp:11
zth::fiber
fiber_type< F >::fiber fiber(F &&f, Args &&... args)
Create and start a new fiber.
Definition async.h:1192
zth::yield
void yield(Fiber *preferFiber=nullptr, bool alwaysYield=false, Timestamp const &now=Timestamp::now())
Allow a context switch.
Definition worker.h:454

Notable other features include:

  • C++20 Coroutine support, to run, share, and co_await a coro between fibers.
  • ARM support with automatic MPU configuration to check stack overflows.
  • Finite State Machine implementation, which allows defining state transitions in an eDSL, and easily transforms into a fiber-aware FSM, properly handling polling timed guards.
  • Extensible Poller framework, which allows poll()-like calls by fibers to be forwarded to a single poller server, which can be user-defined for custom pollable types.
  • Inter-fiber signaling, such as a mutex, semaphore, signal, and future.

Check out the examples for more details, including the full explanation of the example above.

Supported platforms are:

  • Ubuntu/macOS/Windows 32/64-bit
  • bare-metal 32-bit ARM (with newlib)
  • gcc 4 or newer
  • C++98 or newer, C99 or newer. However, compiling for later C++ standards adds features and improves performance.

Check out the dist directory for example targets.

How to build

To install all build dependencies, run dist/<platform>/bootstrap (as Administrator under Windows). Next, run dist/<platform>/build to build the library and all examples. By default, release builds are generated. To do debug builds, pass Debug as command line argument to dist/<platform>/build. VS Code configuration is available too.

After building, check out the doxygen/html directory for documentation.

How to integrate in your project

Configure Zth options as required, like this:

set(ZTH_THREADS OFF CACHE BOOL "Disable threads" FORCE)
# Override search path to your own zth_config.h.
target_include_directories(libzth BEFORE PUBLIC ${CMAKE_SOURCE_DIR}/include)

See cmake/zth.cmake for the available options. Next, add libzth's cmake directory to your CMAKE_MODULE_PATH and include(zth). Then, just link to libzth.

This also works for cross-compiling. Refer to dist/qemu-arm-a15/README-ARM.md for some hints when compiling for bare-metal ARM.

Note that zth_config.h can be provided by the user to optimize the configuration for a specific target. However, its include path must be available while compiling libzth itself. After installing the library, the configuration cannot be changed.

How to run

Zth checks for environment variables, which are listed below. The environment is (usually) only checked once, so dynamically changing the variables after startup has no effect to Zth's behavior.

  • ZTH_CONFIG_ENABLE_DEBUG_PRINT
    When set to 1, debug prints are enabled. Disabled by default. For non-debug builds, all debug prints are removed from the binary, so they cannot be enabled in that case.
  • ZTH_CONFIG_DO_PERF_EVENT
    When set to 1, perf VCD file generation is enabled. Disabled by default.
  • ZTH_CONFIG_DO_PERF_SYSCALL
    When set to 1, the perf VCD logs will contain all calls to Zth's special functions. Enabled by default.
  • ZTH_CONFIG_CHECK_TIMESLICE_OVERRUN When set to 1, check at every context switch if the timeslice was overrun significantly. Only the longest overrun is reported. Enabled by default in the debug build, not available in release builds.

Related

A predecessor project was called Xi, as the Greek capital symbol suggests parallel threads. In this project, preemptive multitasking is implemented. In the same context, the Z(eta) symbol suggests that threads are not parallel, but they explicitly yield from one to another.

GNU Pth has been a great inspiration for this library.

License

(Most of) this project is licensed under the terms of the Mozilla Public License, v. 2.0, as specified in LICENSE. This project complies to REUSE.