Add section about custom memory management using polymorphic allocators

.github/workflows/build_linux.yml

@@ -77,6 +77,34 @@ jobs:
         build_conan/ZserioTutorialCpp write_boss
         build_conan/ZserioTutorialCpp read
 
+    - name: Build Zserio C++ custom memory management tutorial
+      run: |
+        mkdir build_pmr
+        cd build_pmr
+        cmake .. -DCMAKE_BUILD_TYPE=Release
+        cmake --build .
+
+    - name: Test Zserio C++ custom memory management tutorial
+      run: |
+        build_pmr/ZserioTutorialCppPmr write_joe
+        build_pmr/ZserioTutorialCppPmr read
+        build_pmr/ZserioTutorialCppPmr write_boss
+        build_pmr/ZserioTutorialCppPmr read
+
+    - name: Build Zserio C++ custom memory management tutorial (sources regeneration)
+      run: |
+        cd build_pmr
+        rm -rd *
+        cmake .. -DCMAKE_BUILD_TYPE=Release -DREGENERATE_CPP_SOURCES=ON
+        cmake --build .
+
+    - name: Test Zserio C++ custom memory management tutorial (sources regeneration)
+      run: |
+        build_pmr/ZserioTutorialCppPmr write_joe
+        build_pmr/ZserioTutorialCppPmr read
+        build_pmr/ZserioTutorialCppPmr write_boss
+        build_pmr/ZserioTutorialCppPmr read
+
     - name: Archive Zserio C++ tutorial binary
       uses: actions/upload-artifact@v3
       with:

.github/workflows/build_windows.yml

@@ -83,6 +83,38 @@ jobs:
         build_conan/Release/ZserioTutorialCpp read
       shell: bash
 
+    - name: Build Zserio C++ custom memory management tutorial
+      run: |
+        mkdir build_pmr
+        cd build_pmr
+        cmake .. -DCMAKE_BUILD_TYPE=Release
+        cmake --build .
+      shell: bash
+
+    - name: Test Zserio C++ custom memory management tutorial
+      run: |
+        build_pmr/ZserioTutorialCppPmr write_joe
+        build_pmr/ZserioTutorialCppPmr read
+        build_pmr/ZserioTutorialCppPmr write_boss
+        build_pmr/ZserioTutorialCppPmr read
+      shell: bash
+
+    - name: Build Zserio C++ custom memory management tutorial (sources regeneration)
+      run: |
+        cd build_pmr
+        rm -rd *
+        cmake .. -DCMAKE_BUILD_TYPE=Release -DREGENERATE_CPP_SOURCES=ON
+        cmake --build .
+      shell: bash
+
+    - name: Test Zserio C++ custom memory management tutorial (sources regeneration)
+      run: |
+        build_pmr/ZserioTutorialCppPmr write_joe
+        build_pmr/ZserioTutorialCppPmr read
+        build_pmr/ZserioTutorialCppPmr write_boss
+        build_pmr/ZserioTutorialCppPmr read
+      shell: bash
+
     - name: Archive Zserio C++ tutorial binary
       uses: actions/upload-artifact@v3
       with:

CMakeLists.txt

@@ -28,14 +28,14 @@ add_subdirectory(${ZSERIO_RUNTIME_DIR} runtime)
 file(GLOB_RECURSE SOURCES_TUTORIAL_API "${TUTORIAL_ZSERIO_GEN_DIR}/tutorial/*.cpp")
 file(GLOB_RECURSE HEADERS_TUTORIAL_API "${TUTORIAL_ZSERIO_GEN_DIR}/tutorial/*.h")
 
-add_library(ZserioTutorialCpplLib STATIC ${SOURCES_TUTORIAL_API} ${HEADERS_TUTORIAL_API})
+add_library(ZserioTutorialCppLib STATIC ${SOURCES_TUTORIAL_API} ${HEADERS_TUTORIAL_API})
 
-set_target_properties(ZserioTutorialCpplLib PROPERTIES CXX_STANDARD 11 CXX_STANDARD_REQUIRED YES
+set_target_properties(ZserioTutorialCppLib PROPERTIES CXX_STANDARD 11 CXX_STANDARD_REQUIRED YES
         CXX_EXTENSIONS NO)
-target_include_directories(ZserioTutorialCpplLib PUBLIC "${TUTORIAL_ZSERIO_GEN_DIR}")
-target_link_libraries(ZserioTutorialCpplLib ZserioCppRuntime)
+target_include_directories(ZserioTutorialCppLib PUBLIC "${TUTORIAL_ZSERIO_GEN_DIR}")
+target_link_libraries(ZserioTutorialCppLib ZserioCppRuntime)
 
 add_executable(ZserioTutorialCpp src/Main.cpp)
 
 set_target_properties(ZserioTutorialCpp PROPERTIES CXX_STANDARD 11 CXX_STANDARD_REQUIRED YES CXX_EXTENSIONS NO)
-target_link_libraries(ZserioTutorialCpp ZserioTutorialCpplLib)
+target_link_libraries(ZserioTutorialCpp ZserioTutorialCppLib)

README.md

@@ -32,6 +32,10 @@ Before we start, make sure you have the following components installed:
 > **For Conan Users**<br/>
 > If you wish to use conan with this tutorial, simply switch to [conan/README.md](conan/README.md).
 
+> **Custom Memory Management with Polymorphic Allocators**<br/>
+> If you wish to learn more about memory management using polymorphic allocators, simply switch to
+> [pmr/README.md](pmr/README.md).
+
 ## Set up dev environment
 
 > Everything has been already set up for you in this repository. If you are very impatient, just go to the
@@ -243,10 +247,7 @@ Then open up your favorite IDE and start using the zserio classes by including t
 that we want to use.
 
 ```cpp
-#include <zserio/BitStreamReader.h>
-#include <zserio/BitStreamWriter.h>
-#include <zserio/BitBuffer.h>
-#include <zserio/FileUtil.h>
+#include <zserio/SerializeUtil.h>
 #include <zserio/Enums.h>
 #include "tutorial/Employee.h"
 ```
@@ -298,31 +299,12 @@ joe.setSkills(skills);
 > `std::vector<tutorial::Experience>& getSkills()` and populating it directly or using the r-value setter
 > `setSkills(std::vector<tutorial::Experience>&&)`.
 
-After we have set all the fields, we have to declare a BitStreamWriter and write the stream:
-
-```cpp
-zserio::BitBuffer bitBuffer(joe.bitSizeOf());
-zserio::BitStreamWriter writer(bitBuffer);
-joe.write(writer);
-```
-
-`bitSizeOf()` method in zserio returns the actual bit size needed for serialization of the structures.
-
-You may now write the stream to the disk using:
+After we have set all the fields, we have to serialize an employee Joe to the file:
 
 ```cpp
-zserio::writeBufferToFile(writer, "employee.zsb");
+zserio::serializeToFile(joe, "employee.zsb");
 ```
 
-You might as well access the BitstreamWriter's buffer by:
-
-```cpp
-const uint8_t* buffer = writer.getWriteBuffer();
-const size_t bufferBitSize = writer.getBufferBitSize();
-```
-
-You could also use the buffer for any other purpose like sending it over rpc or use it internally.
-
 **Voila!** You have just serialized your first data with zserio.
 
 **Congratulations!**
@@ -345,19 +327,11 @@ boss.setBonus(10000);
 
 The rest is pretty similar. Check the code to see the rest.
 
-When deserializing the zserio bit stream, we start with reading the file to BitBuffer together with
-BitStreamReader construction:
-
-```cpp
-const zserio::BitBuffer bitBuffer = zserio::readBufferFromFile(employee.zsb);
-zserio::BitStreamReader reader(bitBuffer);
-```
-
-We declare an object of class Employee and deserialize the buffer with the help of the BitStreamReader we just
-created. After this call all the fields within `employee` will be set.
+When deserializing the zserio bit stream, we can call `deserializeFromFile` utility from the runtime library.
+After this call all the fields within `employee` will be set.
 
 ```cpp
-tutorial::Employee employee(reader);
+const tutorial::Employee employee = zserio::deserializeFromFile<tutorial::Employee>(employeeFile);
 ```
 
 We can now access the filled employee object via the respective getters. We still need to check for optionals

conan/README.md

@@ -1,4 +1,4 @@
-# Zserio C++ Quick Start Tutorial - Instructions for Conan Users
+# Instructions for Conan Users
 
 ## Installation & Prerequisites
 

pmr/CMakeLists.txt

@@ -0,0 +1,42 @@
+cmake_minimum_required (VERSION 3.5 FATAL_ERROR)
+project (ZserioTutorialCppPmr)
+
+option(REGENERATE_CPP_SOURCES "Regenerate C++ sources using the latest zserio from GitHub release" OFF)
+
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../cmake")
+include(zserio_download)
+
+download_zserio("${CMAKE_CURRENT_BINARY_DIR}/download" ZSERIO_JAR ZSERIO_RUNTIME_DIR)
+
+set(TUTORIAL_ZSERIO_GEN_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src")
+
+if (REGENERATE_CPP_SOURCES)
+    find_package(Java REQUIRED)
+
+    MESSAGE(STATUS "Compiling zserio tutorial schema")
+    execute_process(COMMAND ${Java_JAVA_EXECUTABLE} -jar "${ZSERIO_JAR}"
+            -cpp ${TUTORIAL_ZSERIO_GEN_DIR} -src ${CMAKE_CURRENT_SOURCE_DIR}/.. tutorial.zs
+            -setCppAllocator polymorphic
+        OUTPUT_VARIABLE ZSERIO_OUTPUT
+        RESULT_VARIABLE ZSERIO_RESULT_CODE)
+    if (ZSERIO_RESULT_CODE)
+        message(FATAL_ERROR "Zserio tool failed!")
+    endif ()
+endif ()
+
+add_subdirectory(${ZSERIO_RUNTIME_DIR} runtime)
+
+file(GLOB_RECURSE SOURCES_TUTORIAL_API "${TUTORIAL_ZSERIO_GEN_DIR}/tutorial/*.cpp")
+file(GLOB_RECURSE HEADERS_TUTORIAL_API "${TUTORIAL_ZSERIO_GEN_DIR}/tutorial/*.h")
+
+add_library(ZserioTutorialCppPmrLib STATIC ${SOURCES_TUTORIAL_API} ${HEADERS_TUTORIAL_API})
+
+set_target_properties(ZserioTutorialCppPmrLib PROPERTIES CXX_STANDARD 11 CXX_STANDARD_REQUIRED YES
+        CXX_EXTENSIONS NO)
+target_include_directories(ZserioTutorialCppPmrLib PUBLIC "${TUTORIAL_ZSERIO_GEN_DIR}")
+target_link_libraries(ZserioTutorialCppPmrLib ZserioCppRuntime)
+
+add_executable(ZserioTutorialCppPmr src/Main.cpp)
+
+set_target_properties(ZserioTutorialCppPmr PROPERTIES CXX_STANDARD 11 CXX_STANDARD_REQUIRED YES CXX_EXTENSIONS NO)
+target_link_libraries(ZserioTutorialCppPmr ZserioTutorialCppPmrLib)