Merge branch 'develop'

Author: fbdtemme

.github/workflows/docs.yml

@@ -8,9 +8,7 @@ on:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
-
+    runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v2
       - name: install dependencies

.github/workflows/sanitizers.yml

@@ -0,0 +1,30 @@
+name: sanitizers
+
+on:
+  push:
+    branches: [ master, develop ]
+  pull_request:
+    branches: [ master, develop ]
+
+jobs:
+  sanitizer:
+    runs-on: ubuntu-20.04
+    strategy:
+      fail-fast: false
+      matrix:
+        sanitizer: [asan, ubsan, lsan]
+        compiler : [ g++-10 ]
+    steps:
+      - uses: actions/checkout@v2
+      - name: configure
+        run: mkdir build && cd build &&
+             cmake -DCMAKE_CXX_COMPILER=${{ matrix.compiler }}
+                   -DBENCODE_BUILD_TESTS=ON
+                   -DBENCODE_BUILD_DOCS=OFF
+                   -DBENCODE_BUILD_BENCHMARKS=OFF
+                   -DBENCODE_ENABLE_COVERAGE=OFF
+                   -DCMAKE_BUILD_TYPE="${{ matrix.sanitizer }}" ..
+      - working-directory: build/
+        run: make
+      - working-directory: build/tests
+        run: ./bencode-tests

.github/workflows/tests.yml

@@ -8,24 +8,20 @@ on:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
-
+    runs-on: ubuntu-20.04
     steps:
     - uses: actions/checkout@v2
-    - name: install g++10
-      run: sudo apt install gcc-10 g++-10
-    - name: configure
+    - name: Configure
       run: mkdir build && cd build &&
            cmake -DCMAKE_CXX_COMPILER=g++-10
                  -DCMAKE_BUILD_TYPE=Debug
                  -DBENCODE_BUILD_TESTS=ON
                  -DBENCODE_ENABLE_COVERAGE=ON
                  -DBENCODE_BUILD_DOCS=OFF
                  -DBENCODE_BUILD_BENCHMARKS=OFF ..
-    - name: build
+    - name: Build tests
       run: cmake --build build
-    - name: test
+    - name: Run tests
       run: cd build && ctest
     - name: Generate and upload coverage to Codecov
       run: bash <(curl -s https://codecov.io/bash) -t ${{ secrets.CODECOV_TOKEN }} -x gcov-10

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.5.0
+
+* Rename event_consumer methods from (begin|end)\_(list|dict) to (begin|end)\_(list|dict).
+  This makes naming more consistent.
+* Add more benchmarks
+* Disable contract checks in release build for improved performance.
+* Fix parsing from a pair of InputItererators.
+* Add string_parsing_mode options to push_parser to allow parsing strings to string_view. 
+* Add experimental SSE4.1 and AVX2 integer parsing backends. Enable SWAR integer parsing by default. 
+
 ## v0.4.0
 
 * Reworked parser internals for increased decoding speed.

CMakeLists.txt

@@ -3,12 +3,16 @@ project(bencode
         DESCRIPTION "A C++20 header-only bencode library."
         HOMEPAGE_URL https://github.com/fbdtemme/bencode
         LANGUAGES CXX
-        VERSION 0.4.0)
+        VERSION 0.5.0)
 
 set(PROJECT_AUTHOR "fbdtemme")
 # Make Find modules in cmake dir available
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
 
+if (NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
 # includes
 include(CTest)
 include(CMakeDependentOption)
@@ -37,23 +41,64 @@ include(external/gsl-lite.cmake)
 include(external/expected-lite.cmake)
 
 option(BENCODE_BUILD_TESTS       "Build tests."          ${BENCODE_MASTER_PROJECT})
-option(BENCODE_BUILD_BENCHMARKS  "Build benchmarks"      ${BENCODE_MASTER_PROJECT})
-option(BENCODE_BUILD_DOCS        "Build documentation"   ${BENCODE_MASTER_PROJECT})
+    option(BENCODE_BUILD_BENCHMARKS  "Build benchmarks"                        OFF)
+option(BENCODE_BUILD_DOCS        "Build documentation"                         OFF)
 option(BENCODE_ENABLE_COVERAGE   "Build tests with coverage flags enabled"     OFF)
 option(BENCODE_ENABLE_INSTALL    "Generate an install target."                  ON)
 
-set(BENCODE_FROM_CHARS_IMPL "swar" CACHE STRING
-        "The implementation to use. Options: serial or swar")
+# Changing these options from their defaults can lead to reduced performance.
+# Benchmark before changing these on your target system!
+
+set(BENCODE_FROM_CHARS_INTEGER_IMPL "swar" CACHE STRING
+        "The implementation to use. Options: serial, swar or sse41, avx2")
+set(BENCODE_FROM_CHARS_STRING_IMPL "serial" CACHE STRING
+        "The implementation to use. Options: serial, swar, sse41, avx2")
+
+
+string(TOLOWER ${BENCODE_FROM_CHARS_INTEGER_IMPL} BENCODE_FROM_CHARS_INTEGER_IMPL)
+string(TOLOWER ${BENCODE_FROM_CHARS_STRING_IMPL}  BENCODE_FROM_CHARS_STRING_IMPL)
 
+if (BENCODE_FROM_CHARS_INTEGER_IMPL STREQUAL swar)
+    message(STATUS "Enabling SWAR integer parsing.")
+elseif(BENCODE_FROM_CHARS_INTEGER_IMPL STREQUAL sse41)
+    message(STATUS "Enabling SSE4.1 integer parsing.")
+    target_compile_options(bencode INTERFACE -msse4)
+elseif(BENCODE_FROM_CHARS_INTEGER_IMPL STREQUAL avx2)
+    message(STATUS "Enabling AVX2 integer parsing.")
+    target_compile_options(bencode INTERFACE -mavx2)
+endif()
+
+if (BENCODE_FROM_CHARS_STRING_IMPL STREQUAL swar)
+    message(STATUS "Enabling SWAR string parsing.")
+elseif(BENCODE_FROM_CHARS_STRING_IMPL STREQUAL sse41)
+    message(STATUS "Enabling SSE4.1 string parsing.")
+    target_compile_options(bencode INTERFACE -msse4)
+elseif(BENCODE_FROM_CHARS_STRING_IMPL STREQUAL avx2)
+    message(STATUS "Enabling AVX2 string parsing.")
+    target_compile_options(bencode INTERFACE -mavx2)
+endif()
 
-string(TOLOWER ${BENCODE_FROM_CHARS_IMPL} BENCODE_FROM_CHARS_IMPL)
+
+    target_compile_definitions(
+        bencode INTERFACE
+        BENCODE_FROM_CHARS_INTEGER_IMPL=${BENCODE_FROM_CHARS_INTEGER_IMPL}
+        BENCODE_FROM_CHARS_STRING_IMPL=${BENCODE_FROM_CHARS_STRING_IMPL}
+)
 
 target_link_libraries(bencode
     INTERFACE
         fmt::fmt-header-only
         nonstd::expected-lite
         gsl::gsl-lite-v1)
 
+string(TOLOWER ${CMAKE_BUILD_TYPE} BENCODE_BUILD_TYPE)
+
+if (BENCODE_BUILD_TYPE STREQUAL release)
+    message(STATUS "Disabling all runtime checking of contracts")
+    target_compile_definitions(bencode INTERFACE gsl_CONFIG_CONTRACT_CHECKING_OFF)
+endif()
+
+
 if (BENCODE_BUILD_TESTS)
     enable_testing()
     message(STATUS "Building tests enabled")
@@ -71,13 +116,6 @@ if (BENCODE_BUILD_DOCS)
 endif()
 
 
-if (BENCODE_FROM_CHARS_IMPL STREQUAL swar)
-    message(STATUS "Enabling SWAR integer parsing.")
-elseif()
-    message(STATUS "Disabling SWAR integer parsing.")
-endif()
-target_compile_definitions(bencode INTERFACE BENCODE_FROM_CHARS_IMPL=${BENCODE_FROM_CHARS_IMPL})
-
 
 if (BENCODE_ENABLE_INSTALL)
     set(bencode_package_name        ${PROJECT_NAME})

README.md

@@ -2,6 +2,7 @@
 
 [![build](https://github.com/fbdtemme/bencode/workflows/build/badge.svg?branch=master)](https://github.com/fbdtemme/bencode/actions?query=workflow%3Abuild)
 [![docs](https://github.com/fbdtemme/bencode/workflows/documentation/badge.svg?branch=master)](https://fbdtemme.github.io/bencode/)
+[![santizers](https://github.com/fbdtemme/bencode/workflows/sanitizers/badge.svg?branch=master)](https://github.com/fbdtemme/bencode/actions?query=workflow%3Asanitizers)
 [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/fbdtemme/bencode)](https://github.com/fbdtemme/bencode/releases)
 [![C++ standard](https://img.shields.io/badge/C%2B%2B-20-blue)](https://isocpp.org/)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/5cc3eec94d8a486dab62afeab5130def)](https://app.codacy.com/manual/floriandetemmerman/bencode?utm_source=github.com&utm_medium=referral&utm_content=fbdtemme/bencode&utm_campaign=Badge_Grade_Dashboard)
@@ -10,7 +11,8 @@
 
 [**Features**](#Features) |
 [**Status**](#Status) |
-[**Documentation**](#Documentation) | 
+[**Documentation**](#Documentation) |
+[**Performance**](#Performance) |
 [**Examples**](#Examples) |
 [**Building**](#Building) | 
 [**Integration**](#Integration) |
@@ -29,19 +31,28 @@ A header-only C++20 bencode serialization/deserialization library. Inspired by t
 
 ## Features
 
-*   Convenient owning representation of bencoded data with `bvalue`.
-*   Fast and memory efficient read-only, non-owning representation into stable buffers of bencoded data with `bview`.
-*   Build-in serialization/deserializaton for most standard containers.
-*   Support for serializing/deserializing to/from user-defined types. 
-*   Parse directly to custom types by satisfying the `EventConsumer` concept.
-*   Throwing and non throwing variants of common functions.
-*   Iterative parsing to protect against stack overflow attacks.
-*   Bencode pointer similar to json pointer.   
-
+* **Feature-rich**. The main goal of this library is to provide a complete bencode library that 
+  provides optimal solutions for all common use cases. `bvalue` is an owning representation of bencoded data
+  and is usefull for creating and modifying bencoded documents. 
+  `bview` is a fast and memory efficient, read-only, non-owning representation into a stable buffer of bencoded data.
+  `bpointer` can be used to access both `bvalue` and `bview` types.
+* **Extensibility**. This library provides built-in serialization and deserialization from/to most standard containers.
+  Support for user-defined types can be added by implementing the necessary extension points.
+  Users can parse directly to their data type of preference by implementing a class satisfying
+  the EventConsumer concept.
+* **Conformance**. This library is 100% conforming to the bencode specification.
+  All parsers validate the input and provide exact error messages.
+* **Security**. Parsing arbitrary user data can be dangerous and you do not want your bittorrent tracker 
+  to crash when a user sends malformed data. All parsers are recursion-free to protect against
+  stack-based buffer overflow attacks. Integer parsing throws when overflows are encountered.
+* **Speed**. While not the primary goal of this project this library provides optimized integer parsing with
+  SWAR techniques. Benchmarks show this library performs well in comparison with other libraries
+  
 ## Status
 
-This library is under active development, but should be fairly stable. 
-The API may change at any release prior to 1.0.0.
+This library is under active development. The API may change at any release prior to 1.0.0.
+Versioning follows the Semantic Versioning Specification.
+
 
 ## Documentation
 
@@ -54,6 +65,19 @@ Value types own the data they refer to and thus need to copy data from the buffe
 View types try to minimize copies from the buffer with bencoded data and instead point
 to data directly inside the buffer. 
 
+Decoding speed was compared for these libraries in alphabetical order:
+
+* [Aetf/QBencode](https://github.com/Aetf/QBencode)
+* [arvidn/libtorrent](https://github.com/arvidn/libtorrent)
+* [iRajul/bencode](https://github.com/iRajul/bencode)
+* [jimporter/bencode.hpp](https://github.com/jimporter/bencode.hpp)
+* [kriben/bencode](https://github.com/kriben/bencode)
+* [outputenable/bencode](https://gitlab.com/outputenable/bencode)
+* [rakshasa/libtorrent](https://github.com/rakshasa/libtorrent)
+* [s3ponia/BencodeParser](https://github.com/s3ponia/BencodeParser)
+* [s3rvac/cpp-bencoding](https://github.com/s3rvac/cpp-bencoding)
+* [theanti9/cppbencode](https://github.com/theanti9/cppbencode)
+
 #### Parsing to value types
 
 ![benchmark-decoding-value](docs/images/benchmark-decoding-value.svg)
@@ -62,7 +86,15 @@ to data directly inside the buffer.
 
 ![benchmark-decoding-view](docs/images/benchmark-decoding-view.svg)
 
-Note: libtorrent does not decode integers until they are actually accessed.
+All benchmarks were build with GCC 10.2.1 with -O3 and run on an intel i7-7700hq.
+
+Notes:
+* arvidn/libtorrent does not decode integers until they are actually accessed. 
+  This gives a performance benefit when decoding but results in slower 
+  access times when retrieving integral values.
+* kriben/bencode support only 32-bit integers and fails on the
+  camelyon17, integers and pneumomia benchmarks
+* iRajul/bencode fails all benchmarks and was excluded from the results.
 
 ## Examples
 
@@ -186,7 +218,7 @@ See the [documentation](https://fbdtemme.github.io/bencode/) for more examples.
 This project requires C++20. 
 Currently only GCC 10 and later is supported.
 
-This library depends on following projects:
+This library uses following projects:
 *   [fmt](https://github.com/fmtlib/fmt)
 *   [gsl-lite](https://github.com/gsl-lite/gsl-lite)
 *   [expected-lite](https://github.com/martinmoene/expected-lite)
@@ -196,23 +228,29 @@ When building tests:
 
 When building benchmarks:
 *   [google/benchmark](https://github.com/google/benchmark)
-*   [libtorrent](https://github.com/arvidn/libtorrent)
-*   [jimporter/bencode](https://github.com/jimporter/bencode)
-*   [s3rvac/cpp-bencoding](https://github.com/s3rvac/cpp-bencoding)
+*   [Boost](https://www.boost.org/)
+*   [Qt5](https://www.qt.io/)
+
 
 When building documentation:
 * [doxygen](https://github.com/doxygen/doxygen>)
 * [sphinx](https://github.com/sphinx-doc/sphinx>)
 * [breathe](https://github.com/michaeljones/breathe>)
+* [shphinx-rtd-theme](https://github.com/readthedocs/sphinx_rtd_theme)
 
-All dependencies for building tests and benchmarks can be fetched from github using
+All dependencies except for boost, Qt5 and documentation dependencies can be fetched from github using
 cmake FetchContent during configuration if no local installation is found.
 
 The tests can be built as every other project which makes use of the CMake build system.
 
 ```{bash}
 mkdir build; cd build;
-cmake .. -DCMAKE_BUILD_TYPE=Debug -DBENCODE_BUILD_TESTS=ON -DBENCODE_BUILD_BENCHMARKS=OFF =DBENCODE_BUILD_DOCS=OFF
+cmake \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DBENCODE_BUILD_TESTS=ON \
+  -DBENCODE_BUILD_BENCHMARKS=OFF \
+  -DBENCODE_BUILD_DOCS=OFF \
+   --build . --target .. 
 make bencode-tests
 ```