Initial public release

libvsync v3.2.0

Co-authored-by: Diogo Behrens <[email protected]>
Co-authored-by: Lilith Oberhauser <[email protected]>
Co-authored-by: Jonathan Schwender <[email protected]>

.clang-format

@@ -0,0 +1,69 @@
+AlignAfterOpenBracket                     : Align
+AlignConsecutiveAssignments               : true
+AlignConsecutiveDeclarations              : false
+AlignConsecutiveMacros                    : true
+AlignEscapedNewlines                      : Right
+AlignOperands                             : true
+AlignTrailingComments                     : true
+AllowAllArgumentsOnNextLine               : false
+AllowAllParametersOfDeclarationOnNextLine : false
+AllowShortBlocksOnASingleLine             : Empty
+AllowShortCaseLabelsOnASingleLine         : false
+AllowShortFunctionsOnASingleLine          : None
+AllowShortIfStatementsOnASingleLine       : Never
+AllowShortLoopsOnASingleLine              : false
+AlwaysBreakAfterReturnType                : TopLevelDefinitions
+AlwaysBreakBeforeMultilineStrings         : true
+BinPackArguments                          : true
+BinPackParameters                         : true
+BreakBeforeBinaryOperators                : None
+BreakBeforeBraces                         : Linux
+BreakBeforeTernaryOperators               : false
+BreakStringLiterals                       : true
+ColumnLimit                               : 80
+ContinuationIndentWidth                   : 4
+DeriveLineEnding                          : false
+DerivePointerAlignment                    : false
+ExperimentalAutoDetectBinPacking          : false
+IncludeBlocks                             : Merge
+IndentCaseLabels                          : true
+IndentGotoLabels                          : false
+IndentPPDirectives                        : BeforeHash
+IndentWidth                               : 4
+IndentWrappedFunctionNames                : false
+KeepEmptyLinesAtTheStartOfBlocks          : false
+Language                                  : Cpp
+MaxEmptyLinesToKeep                       : 2
+PointerAlignment                          : Right
+ReflowComments                            : true
+SortIncludes                              : false
+SpaceAfterCStyleCast                      : false
+SpaceAfterLogicalNot                      : false
+SpaceBeforeAssignmentOperators            : true
+SpaceBeforeParens                         : ControlStatements
+SpaceBeforeSquareBrackets                 : false
+SpaceInEmptyBlock                         : false
+SpaceInEmptyParentheses                   : false
+SpacesBeforeTrailingComments              : 1
+SpacesInCStyleCastParentheses             : false
+SpacesInConditionalStatement              : false
+SpacesInContainerLiterals                 : false
+SpacesInParentheses                       : false
+SpacesInSquareBrackets                    : false
+TabWidth                                  : 4
+UseTab                                    : Never
+ForEachMacros:
+- await_while
+- await_do
+# How to format } while_await() ?
+
+StatementMacros:
+- V_DEFINE_FUNC
+
+WhitespaceSensitiveMacros:
+- V_ASM
+
+TypenameMacros:
+- V_MAP_T
+- V_MAP_R
+- V_MAP_A

.gitignore

@@ -0,0 +1 @@
+doc.h

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.2.0] - 2023-16-10
+
+Initial public release.

CMakeLists.txt

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(
+    libvsync
+    LANGUAGES C
+    VERSION 3.2.0
+    DESCRIPTION "Verified library of atomics, synchronization primitives and concurrent data structures")
+
+option(LIBVSYNC_ADDRESS_SANITIZER "Compile with -fsanitize=address" "off")
+option(LIBVSYNC_CODECHECK_BINSCOPE "Compile with necessary flags for binscope" "off")
+
+include(GNUInstallDirs)
+include(cmake/export.cmake)
+
+add_library(vsync INTERFACE)
+
+target_include_directories(
+    vsync INTERFACE "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+                    "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>")
+
+install(DIRECTORY include/vsync DESTINATION include)
+install(TARGETS vsync EXPORT ${PROJECT_TARGETS})
+
+
+if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+    set(LIBVSYNC_OPEN_DISTRO_TESTING "on")
+    enable_testing()
+    add_subdirectory(test)
+    if(LIBVSYNC_ADDRESS_SANITIZER)
+        target_compile_options(vsync INTERFACE -fsanitize=address)
+        target_link_options(vsync INTERFACE -fsanitize=address)
+    endif()
+    if(LIBVSYNC_CODECHECK_BINSCOPE)
+        target_compile_definitions(vsync INTERFACE _FORTIFY_SOURCE=2)
+        target_compile_options(vsync INTERFACE -fstack-protector-strong -fstack-protector-all -fPIE -fPIC -O2)
+        target_link_options(vsync INTERFACE -s -pie -Wl,-z,relro,-z,now)
+    endif()
+endif()
+

LICENSE

@@ -0,0 +1,8 @@
+Copyright (C) 2023 Huawei Technologies Co., Ltd.
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,100 @@
+# libvsync
+
+libvsync is a C header-only library that contains most essential building blocks for concurrent applications.
+That includes atomic operations, synchronization primitives and concurrent data structures.
+
+All synchronization primitives have been verified and optimized with respect to weak memory models (WMM).
+They also served as benchmarks for our ASPLOS'21 publication:
+[VSync: Push-Button Verification and Optimization for Synchronization Primitives on Weak Memory Models](https://dl.acm.org/doi/abs/10.1145/3445814.3446748).
+
+All data structures have been verified with respect to WMM.
+
+The currently open sourced implementations
+are algorithms from the literature implemented on top of our atomics, verified with model checkers,
+and optimized using vsyncer.
+
+We plan to gradually release more and more algorithms, including some of our own highly optimized algorithms.
+
+
+## API Documentation
+See [doc](doc/api/vsync/README.md) for details and usage examples.
+
+## User Guide
+
+To install and use libvsync
+
+You need the following dependencies:
+- git
+- CMake 3.16 or newer
+- GNU make or Ninja
+- a semi-recent C-compiler: clang or gcc.
+
+_Note: libvsync has been tested on Ubuntu 22.04 with Clang-14, and openEuler 22.03 (LTS=SP1) with gcc 10.3.1_
+
+
+### for installation:
+
+```bash
+git clone <libvsync-clone-url>
+cd libvsync
+cmake -S. -Bbuild -DCMAKE_INSTALL_PREFIX=/usr/local
+cmake --build build -j $(nproc)
+sudo cmake --install build
+```
+
+### to use without installation:
+You copy the header files or configure your compiler
+to point to the headers directly. You must keep the files under `vsync/`, e.g.,
+`my_project/include/vsync/*.h`.
+
+### to run tests:
+```bash
+cd libvsync
+cmake -S. -Bbuild
+cmake --build build
+ctest --test-dir build
+```
+
+### to integrate in a CMake project
+
+The project provides a CMake `INTERFACE` library called `vsync`, which you can link into your own
+CMake targets.
+
+To add libvsync to your project you can just use the regular CMake mechanisms such as
+`add_subdirectory()`, or e.g. the CPM dependency manager.
+Below an example which fetches libvsync from a remote git forge without any external dependencies:
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+    libvsync
+    GIT_REPOSITORY <libvsync-clone-https-url>
+    GIT_TAG v3.0 # You may also specify a branch name or commit hash here.
+)
+FetchContent_MakeAvailable(libvsync)
+```
+
+## Developer Guide
+
+If you would like to contribute to libvsync, check out [developer guide](developer_guide.md).
+
+## License
+This library is distributed under the [MIT](LICENSE) license.
+
+## Contact
+For questions write us an email: `vsync AT huawei DOT com`
+
+## Disclaimer
+- A few algorithms require using safe memory reclamation scheme (SMR). In their examples you will find `gdump` used for that purpose.
+The current version of libvsync does not contain `gdump`. Users can replace `gdump` with their own quiescent-state/grace-period based SMR scheme. We intend to release SMR schemes in future releases.
+
+- Note that due to the fact that model checkers do not scale well with respect to number of threads/operations, our verification is not complete and cannot guarantee the absence of bugs. However, it does
+increase confidence in our implementations especially on hardware with WMM (e.g ARM).
+
+
+## Acknowledgement
+
+This project is under the support of [OpenHarmony Concurrency & Coordination TSG (Technical Support Group), 并发与协同TSG][tsg].
+
+[tsg]: https://www.openharmony.cn/techCommittee/aboutTSG

cmake/config.cmake.in

@@ -0,0 +1,4 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")
+check_required_components("@PROJECT_NAME@")

cmake/export.cmake

@@ -0,0 +1,27 @@
+set(CONFIG_IN_FILE "cmake/config.cmake.in")
+
+if(NOT DEFINED PROJECT_TARGETS)
+    set(PROJECT_TARGETS "${PROJECT_NAME}Targets")
+endif()
+
+set(PROJECT_CMAKE_DIR "${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake")
+set(PROJECT_CONFIG_FILE "${PROJECT_BINARY_DIR}/${PROJECT_NAME}Config.cmake")
+set(PROJECT_VERSION_FILE
+    "${PROJECT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake")
+
+include(CMakePackageConfigHelpers)
+configure_package_config_file(${CONFIG_IN_FILE} ${PROJECT_CONFIG_FILE}
+                              INSTALL_DESTINATION ${PROJECT_CMAKE_DIR})
+
+write_basic_package_version_file(
+    ${PROJECT_VERSION_FILE}
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion)
+
+install(
+    EXPORT ${PROJECT_TARGETS}
+    FILE ${PROJECT_TARGETS}.cmake
+    NAMESPACE ${PROJECT_NAME}::
+    DESTINATION ${PROJECT_CMAKE_DIR})
+install(FILES ${PROJECT_CONFIG_FILE} ${PROJECT_VERSION_FILE}
+        DESTINATION ${PROJECT_CMAKE_DIR})

cmake/v_add_test.cmake

@@ -0,0 +1,119 @@
+include_guard(GLOBAL)
+
+option(BUILD_WITH_CTEST "Add test fixture to build before testing" ON)
+
+# Wrapper around `add_test` that adds a dependency on the build. Parameters:
+# NAME: Test name, COMMAND: First value is the binary, anything else gets passed
+# through.
+function(v_add_bin_test)
+    set(options "")
+    # `add_test` command can have multiple values, but we are only interested in
+    # the first one, which is the executable target. All arguments are available
+    # in `PREFIX_UNPARSED_ARGUMENTS` and will be passed through to the final
+    # `add_test` COMMAND.
+    set(single_value_args "NAME" "COMMAND")
+    set(multi_value_args "")
+    set(mandatory_arguments NAME COMMAND)
+    cmake_parse_arguments(TST "${options}" "${single_value_args}"
+                          "${multi_value_args}" ${ARGN})
+
+    foreach(argname ${mandatory_arguments})
+        if(NOT DEFINED "TST_${argname}")
+            message(
+                FATAL_ERROR
+                    "Missing mandatory parameter: ${argname}.\n"
+                    "Help: The following parameters are required: ${mandatory_arguments}"
+            )
+        endif()
+    endforeach()
+
+    if(NOT TARGET "${TST_COMMAND}")
+        message(
+            FATAL_ERROR
+                "COMMAND argument ${TST_COMMAND} to `v_add_bin_test` was not a CMake target"
+        )
+    endif()
+
+    add_test(NAME "${TST_NAME}" COMMAND "${TST_COMMAND}"
+                                        ${TST_UNPARSED_ARGUMENTS})
+
+    if(BUILD_WITH_CTEST)
+        if(NOT TEST "build_${TST_COMMAND}")
+            add_test(NAME "build_${TST_COMMAND}"
+                     COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR}
+                             --target "${TST_COMMAND}")
+            set_tests_properties(
+                "build_${TST_COMMAND}" PROPERTIES FIXTURES_SETUP
+                                                  "build_${TST_COMMAND}")
+        endif()
+        set_tests_properties("${TST_NAME}" PROPERTIES FIXTURES_REQUIRED
+                                                      "build_${TST_COMMAND}")
+    endif()
+
+endfunction()
+
+function(v_add_bin_test_advanced)
+    set(options "")
+    set(single_value_args "NAME" "TIMEOUT" "COST" "PROCESSORS")
+    set(multi_value_args "")
+
+    cmake_parse_arguments(TST "${options}" "${single_value_args}"
+                          "${multi_value_args}" ${ARGN})
+
+    v_add_bin_test(NAME "${TST_NAME}" ${TST_UNPARSED_ARGUMENTS})
+
+    # Default COST to the Timeout value (if set). If `COST` is explicitly set,
+    # it will later override this default cost.
+    if("${TST_TIMEOUT}")
+        set_tests_properties("${TST_NAME}" PROPERTIES COST "${TST_TIMEOUT}")
+    endif()
+
+    # Override default values with explicit values (if provided)
+    foreach(ctest_prop TIMEOUT COST PROCESSORS)
+        if(DEFINED "TST_${ctest_prop}")
+            set_tests_properties(
+                "${TST_NAME}" PROPERTIES "${ctest_prop}" "${TST_${ctest_prop}}")
+        endif()
+    endforeach()
+
+endfunction()
+
+# Adds options that override the default values for stress tests
+function(v_add_heavy_stress_test)
+    set(options "")
+    set(single_value_args
+        "NAME"
+        "STRESS_TIMEOUT"
+        "STRESS_COST"
+        "STRESS_PROCESSORS"
+        "TIMEOUT"
+        "COST"
+        "PROCESSORS")
+    set(multi_value_args "")
+
+    cmake_parse_arguments(TST "${options}" "${single_value_args}"
+                          "${multi_value_args}" ${ARGN})
+
+    set(ctest_prop_args "")
+    if("${TST_NAME}" MATCHES "_stress_")
+        foreach(ctest_prop "TIMEOUT" "COST" "PROCESSORS")
+            if(DEFINED "TST_STRESS_${ctest_prop}")
+                list(APPEND ctest_prop_args "${ctest_prop}"
+                     ${TST_STRESS_${ctest_prop}})
+            elseif(DEFINED "TST_${ctest_prop}")
+                list(APPEND ctest_prop_args "${ctest_prop}"
+                     ${TST_${ctest_prop}})
+            endif()
+        endforeach()
+    else()
+        foreach(ctest_prop "TIMEOUT" "COST" "PROCESSORS")
+            if(DEFINED "TST_${ctest_prop}")
+                list(APPEND ctest_prop_args "${ctest_prop}"
+                     ${TST_${ctest_prop}})
+            endif()
+        endforeach()
+    endif()
+    v_add_bin_test_advanced(NAME "${TST_NAME}" ${ctest_prop_args}
+                            ${TST_UNPARSED_ARGUMENTS})
+
+endfunction()