网络/光纤>> zth>> 返回
项目作者： jhrutgers

项目描述 ：
Cross-platform cooperative multitasking (fiber) framework.
高级语言： C++
项目地址: git://github.com/jhrutgers/zth.git
创建时间： 2020-07-27T11:19:20Z
项目社区：https://github.com/jhrutgers/zth
开源协议：GNU Lesser General Public License v3.0
下载


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 the async keyword:

  1. #include <zth>
  2. #include <cstdio>
  4. void world()
  5. {
  6.     printf("World!!1\n");
  7. }
  8. zth_fiber(world)
  10. void hello()
  11. {
  12.     async world();
  13.     printf("Hello\n");
  14. }
  15. zth_fiber(hello)
  17. int main_fiber(int argc, char** argv)
  18. {
  19.     async hello();
  20.     return 0;
  21. }

Notable other features include:

  • Finite State Machine implementation, which allows defining state transitions
    in an eDSL, and easily transfers a fiber 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. This does effectively:

  1. mkdir build
  2. cd build
  3. cmake ../../..
  4. cmake --build .

By default, release builds are generated. To do debug builds, pass Debug as
command line argument to dist/<platform>/build, or do something like:

  1. cmake ../../.. -D CMAKE_BUILD_TYPE=Debug

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

How to integrate in your project

Include the Zth top-level CMakeLists.txt in your project, and link to
libzth. Configure Zth options as required, like this:

  1. set(ZTH_HAVE_LIBZMQ OFF CACHE BOOL "Disable ZMQ" FORCE)
  2. set(ZTH_THREADS OFF CACHE BOOL "Disable threads" FORCE)
  3. set(ZTH_BUILD_EXAMPLES OFF CACHE BOOL "Disable Zth examples" FORCE)
  4. set(ZTH_TESTS OFF CACHE BOOL "Disable Zth tests" FORCE)
  6. add_subdirectory(zth)
  8. # Override search path to your own zth_config.h.
  9. target_include_directories(libzth BEFORE PUBLIC ${CMAKE_SOURCE_DIR}/include)

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 enabeled. 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.

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

This project is licensed under the terms of the Mozilla Public License, v. 2.0,
as specified in LICENSE.