Skip to content

Latest commit

 

History

History
190 lines (148 loc) · 7.46 KB

README.md

File metadata and controls

190 lines (148 loc) · 7.46 KB
Raw

StreamPU

GitLab Pipeline Status GitLab Code Coverage Documentation License: MIT

StreamPU is a Domain Specific Embedded Language (DSEL) for streaming applications. It comes in the form of a C++11 library to link with.

Sequence and pipeline

Here are the main features of StreamPU:

  • Definition of dataflow components: modules, tasks and sockets
  • Elementary modules and tasks implementations
  • Multi-threaded runtime with replication and pipeline parallel constructs

This DSEL/library is suitable for SDR systems, audio/video processing and more generally it matches single-rate Synchronous DataFlow (SDF) streaming applications.

Please note that this library was previously named AFF3CT-core as it was first extracted from AFF3CT. Now that it is no longer specific to channel coding and digital communications, the project has been renamed to StreamPU, which is a more meaningful name.

Library Compilation & Installation

This project uses CMake as the main build system and it provides the following CMake options:

  • SPU_COMPILE_STATIC_LIB: Compile the static library (default = ON)
  • SPU_COMPILE_SHARED_LIB: Compile the shared library (default = OFF)
  • SPU_LINK_HWLOC: Link with the hwloc library (used for threads pinning) (default = OFF)
  • SPU_COLORS: Enable the colors in the terminal (default = ON)
  • SPU_TESTS: Enable the compilation of the tests (default = ON)
  • SPU_STACKTRACE: Print the stack trace when an exception is raised (and link with the cpptrace lib) (default = ON)
  • SPU_STACKTRACE_SEGFAULT: Try to print the stack trace when a segfault occurs (and link with the cpptrace lib) (default = OFF)
  • SPU_SHOW_DEPRECATED: Print message each time a deprecated function is called (default = OFF)
  • SPU_FAST: Remove checks to speedup the code (default = OFF)

Build the library in debug mode:

mkdir build_debug
cd build_debug
cmake ..
cmake --build . -j 4
ctest

Build the library in release mode:

mkdir build_release
cd build_release
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_CXX_FLAGS="-Wall -march=native -funroll-loops"
cmake --build . -j 4
ctest

Install the library on the system (/usr/local):

cmake --install .

Install the library in a custom path (/opt/streampu):

cmake --install . --prefix /opt/streampu/

Link with the Library

StreamPU exposes two CMake targets:

  • spu::spu-static-lib: StreamPU static library, includes and definitions (compiled by default)
  • spu::spu-shared-lib: StreamPU shared library, includes and definitions

It is possible to link with StreamPU from a sub-directory or from an installed library. Both methods are described in the next sections.

From a Sub-directory

Let us suppose that we want to produce the my-exe executable that will links with StreamPU and that the StreamPU repository is located at my-exe-root/lib/streampu/. Here is a minimal CMakeLists.txt file to generate it:

cmake_minimum_required(VERSION 3.5)

project(my_project CXX)

# require C++11 compiler ------------------------------------------------------
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# create the `my-exe` executable from `src/main.cpp` --------------------------
add_executable(my-exe ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)

# compile `StreamPU` static lib -----------------------------------------------
option(SPU_TESTS "" OFF) # do NOT compile the tests
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/lib/streampu/)

# `my-exe` links with `StreamPU` static lib -----------------------------------
target_link_libraries(my-exe PUBLIC spu::spu-static-lib)

# `my-exe` finds and links with thread library --------------------------------
set(CMAKE_THREAD_PREFER_PTHREAD ON)
set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
target_link_libraries(my-exe PUBLIC Threads::Threads)

# `my-exe` links with `cpptrace` (`SPU_STACKTRACE=ON`) ------------------------
if(SPU_STACKTRACE OR SPU_STACKTRACE_SEGFAULT)
  target_link_libraries(my-exe PUBLIC cpptrace::cpptrace)
endif()

From an Installed Library

Let us suppose that we want to produce the my-exe executable that links with StreamPU static library installed on the system. Here is a minimal CMakeLists.txt file to generate it:

cmake_minimum_required(VERSION 3.5)

project(my_project CXX)

# require C++11 compiler ------------------------------------------------------
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# create the `my-exe` executable from `src/main.cpp` --------------------------
add_executable(my-exe ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)

# find and link with thread library -------------------------------------------
set(CMAKE_THREAD_PREFER_PTHREAD ON)
set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
target_link_libraries(my-exe PUBLIC Threads::Threads)

# find and link with `cpptrace` if installed (if not, don't) ------------------
find_package(cpptrace CONFIG 0.4.1)
if (cpptrace_FOUND)
  target_link_libraries(my-exe PUBLIC cpptrace::cpptrace)
endif()

# find and link with `StreamPU` -----------------------------------------------
find_package(StreamPU CONFIG 0.0.0 REQUIRED)
target_link_libraries(my-exe PUBLIC spu::spu-static-lib)

If StreamPU is installed in a specific location (for instance: /opt/streampu), you can help CMake to find it as follow:

cmake .. -DStreamPU_DIR=/opt/streampu/lib/cmake/streampu

Or, if StreamPU has been compiled with the cpptrace library:

cmake .. -DStreamPU_DIR=/opt/streampu/lib/cmake/streampu -Dcpptrace_DIR=/opt/streampu/lib/cmake/cpptrace

Documentation

License

The project is licensed under the MIT license.

How to cite StreamPU

The main contributions of this work are described in the following journal article:

  • A. Cassagne, R. Tajan, O. Aumage, D. Barthou, C. Leroux and C. Jégo,
    “A DSEL for High Throughput and Low Latency Software-Defined Radio on Multicore CPUs,“
    Wiley Concurrency and Computation: Practice and Experience (CCPE), 2023.
    [Open access article] [Bibtex entry]