feat: tcmalloc and cache-line alignment

milsanore · milsanore · commit cce2b0675da0 · 2025-10-24T19:53:50.000+11:00
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,15 @@
+name: Build
+
+# run the vanilla build pipeline on commits to feature branches, or PRs on master
+
+on:
+  push:
+    branches:
+      - "*"
+  pull_request:
+    branches: [ master ]
+
+    
+jobs:
+  call-reusable:
+    uses: ./.github/workflows/reusable_build.yml
diff --git a/.github/workflows/commits.yml b/.github/workflows/commits.yml
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
@@ -1,4 +1,6 @@
-name: Daily
+name: Nightly
+
+# run the vanilla build pipeline every night on the master branch
 
 on:
   schedule:
@@ -7,6 +9,6 @@ on:
 
 jobs:
   call-reusable:
-    uses: ./.github/workflows/clean_build_test.yml
+    uses: ./.github/workflows/reusable_build.yml
     with:
       ref: ${{ 'master' }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,5 +1,7 @@
 name: Release
 
+# run the Release pipeline when a release is created, and attach artifacts
+
 on:
   release:
     types: [published]  # Triggers when a release is published
diff --git a/.github/workflows/reusable_build.yml b/.github/workflows/reusable_build.yml
@@ -1,14 +1,16 @@
 name: Reusable Build Workflow
 
+# reusable build pipeline
+# creates a Debug build, and runs assorted tests
+
 on:
   workflow_call:
     inputs:
       ref:
         description: 'Git reference to checkout'
         required: false
         type: string
-
-# workflow_dispatch: # Allows manual triggering
+  workflow_dispatch: # Allows manual run from GitHub UI
 
 jobs:
   build_and_test:
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -34,6 +34,7 @@ find_package(Boost REQUIRED)
 find_package(concurrentqueue REQUIRED)
 find_package(efsw REQUIRED)
 find_package(ftxui REQUIRED)
+find_package(gperftools REQUIRED)
 find_package(Microsoft.GSL REQUIRED)
 find_package(GTest REQUIRED)
 find_package(OpenSSL REQUIRED)
@@ -47,6 +48,7 @@ target_link_libraries(traderlib PUBLIC
     concurrentqueue::concurrentqueue
     efsw::efsw
     ftxui::ftxui
+    gperftools::gperftools
     Microsoft.GSL::GSL
     OpenSSL::SSL
     OpenSSL::Crypto
diff --git a/README.md b/README.md
@@ -80,10 +80,10 @@ NB: this app uses `make` as a recipe book, but it's not essential:
   - OrderMassCancelRequest on error
   - quickfix database vs fix8 equivalent
 - ✅ subscribe to price updates
+- ✅ use a precise number type for money
 - create a basic trading signal (e.g. standard deviations)
-- use a precise number type for money
 - fire an order
-- test in the Binance test environment
+- ✅ test in the Binance test environment
 - momentum indicators
 - throughput indicators (messages/sec)
 - orders
@@ -151,12 +151,13 @@ NB: this app uses `make` as a recipe book, but it's not essential:
   - FTXUI snapshot testing
 - performance
   - ✅ store prices and sizes as integrals (ticks as `uint64_t`) for performance
+  - ✅ cache line alignment
   - release compile flags
   - profiling (valgrind/cachegrind)
-  - gperftools
   - profile-guided optimization (pgo)
   - load test with mocked FIX server
-  - tcmalloc / gperftools
+  - tcmalloc (Full/Minimal) / gperftools
+    - profiling tcmalloc
 - latency
   - sparse arrays & flat matrix
   - memory-mapped files
diff --git a/conan.lock b/conan.lock
@@ -9,6 +9,7 @@
         "libsodium/1.0.20#d2baa92ed999abe295ff63e2ee25b4f3%1743063880.072",
         "libbacktrace/cci.20210118#a7691bfccd8caaf66309df196790a5a1%1722218217.276",
         "gtest/1.17.0#5224b3b3ff3b4ce1133cbdd27d53ee7d%1755784855.585",
+        "gperftools/2.17.2#1de28b5116961a072cf9a2d62f231d2a%1759579795.648",
         "ftxui/6.0.2#1b49d899f377591328fd17df1b3fd98e%1744735500.697",
         "fmt/11.2.0#579bb2cdf4a7607621beea4eb4651e0f%1746298708.362",
         "efsw/1.4.1#a4dc44b2fa9fa5a55081e365b1301d4c%1731488680.092",
diff --git a/conanfile.txt b/conanfile.txt
@@ -4,8 +4,9 @@ boost/1.88.0
 concurrentqueue/1.0.4
 efsw/1.4.1
 ftxui/6.0.2
-ms-gsl/4.2.0
+gperftools/2.17.2
 gtest/1.17.0
+ms-gsl/4.2.0
 openssl/3.5.2
 quickfix/1.15.1
 libsodium/1.0.20
diff --git a/src/binance/auth.h b/src/binance/auth.h
@@ -1,9 +1,11 @@
 #pragma once
 
 #include <mutex>
+#include <new>
 #include <string>
 #include <vector>
 
+#include "../utils/env.h"
 #include "iauth.h"
 
 namespace binance {
@@ -41,7 +43,7 @@ class Auth final : public IAuth {
  private:
   // when authenticating with Binance, each session authenticates independently,
   // and in parallel. requires synchronisation because of file access.
-  mutable std::mutex mutex_;
+  alignas(utils::Env::CACHE_LINE_SIZE) mutable std::mutex mutex_;
 
   std::string& api_key_;
   std::string& private_pem_path_;
diff --git a/src/binance/fix_app.h b/src/binance/fix_app.h
@@ -42,10 +42,10 @@ class FixApp final : public FIX::Application, public FIX44::MessageCracker {
   // TODO: we will have one of these per instrument
 
  private:
-  static constexpr std::string THREAD_NAME_ = "tradercppFIX2";
-  static constexpr std::string PRICE_SESSION_QUALIFIER_ = "PX";
-  static constexpr std::string TRADE_SESSION_QUALIFIER_ = "TX";
-  static constexpr std::string ORDER_SESSION_QUALIFIER_ = "OX";
+  static inline constexpr std::string THREAD_NAME_ = "tradercppFIX2";
+  static inline constexpr std::string PRICE_SESSION_QUALIFIER_ = "PX";
+  static inline constexpr std::string TRADE_SESSION_QUALIFIER_ = "TX";
+  static inline constexpr std::string ORDER_SESSION_QUALIFIER_ = "OX";
   const std::vector<std::string>& symbols_;
   const std::unique_ptr<IAuth> auth_;
   const uint16_t MAX_DEPTH_;
diff --git a/src/binance/message_handling_mode.h b/src/binance/message_handling_mode.h
@@ -19,7 +19,7 @@ struct MessageHandlingMode {
     SEQUENTIAL = 2,
   };
 
-  static constexpr uint16_t FIELD_ID = 25'035;
+  static inline constexpr uint16_t FIELD_ID = 25'035;
 
   static constexpr uint16_t to_int(Mode m) noexcept { return static_cast<uint16_t>(m); }
 
diff --git a/src/binance/worker.h b/src/binance/worker.h
@@ -18,7 +18,7 @@ namespace binance {
 /// @brief Binance DI container
 class Worker final {
  public:
-  static constexpr std::string THREAD_NAME_ = "tradercppFIX1";
+  static inline constexpr std::string THREAD_NAME_ = "tradercppFIX1";
   Worker(std::unique_ptr<FixApp> app,
          std::unique_ptr<FIX::FileStoreFactory> store,
          FIX::SessionSettings settings,
diff --git a/src/core/bid_ask.h b/src/core/bid_ask.h
@@ -2,10 +2,12 @@
 
 #include <cmath>
 
+#include "../utils/env.h"
+
 namespace core {
 
 /// @brief basic bid/ask level
-struct BidAsk {
+struct alignas(utils::Env::CACHE_LINE_SIZE) BidAsk {
  public:
   BidAsk() = default;
   explicit BidAsk(u_int64_t bidsz, u_int64_t bidpx, u_int64_t askpx, u_int64_t asksz)
@@ -14,7 +16,7 @@ struct BidAsk {
   // NB: using UINT64_MAX as a sentinel value.
   // maybe it's smarter to use UINT64_MAX-1 as a sentinel,
   // in order to catch overflow prices in the market?
-  static constexpr u_int64_t SENTINEL_ = UINT64_MAX;
+  static inline constexpr u_int64_t SENTINEL_ = UINT64_MAX;
 
   u_int64_t bid_sz = SENTINEL_;
   u_int64_t bid_px = SENTINEL_;
diff --git a/src/core/order_book.cpp b/src/core/order_book.cpp
@@ -159,8 +159,9 @@ void OrderBook::handle_price_level_update(
     FIX::MDUpdateAction action,
     const FIX44::MarketDataIncrementalRefresh::NoMDEntries& group,
     bool is_book_clear_needed) {
-  uint64_t px = utils::Double::toUint64(
-      group.get(e_px_).getValue(), binance::Config::get_price_ticks_per_unit(symbol));
+  uint64_t px =
+      utils::Double::toUint64(group.get(temp_vars_.e_px).getValue(),
+                              binance::Config::get_price_ticks_per_unit(symbol));
   //
   switch (action.getValue()) {
     case FIX::MDUpdateAction_DELETE:
@@ -173,8 +174,9 @@ void OrderBook::handle_price_level_update(
       [[fallthrough]];
     }
     case FIX::MDUpdateAction_NEW: {
-      uint64_t sz = utils::Double::toUint64(
-          group.get(e_sz_).getValue(), binance::Config::get_size_ticks_per_unit(symbol));
+      uint64_t sz =
+          utils::Double::toUint64(group.get(temp_vars_.e_sz).getValue(),
+                                  binance::Config::get_size_ticks_per_unit(symbol));
       bid_ask_map[px] = sz;
     } break;
     default:
diff --git a/src/core/order_book.h b/src/core/order_book.h
@@ -8,6 +8,7 @@
 #include <mutex>
 
 #include "../binance/symbol.h"
+#include "../utils/env.h"
 #include "absl/container/btree_map.h"
 #include "bid_ask.h"
 
@@ -37,14 +38,16 @@ class OrderBook {
  private:
   // mutex for reading/writing to bid/ask maps
   // NB: UI-bound, so performance is acceptable
-  mutable std::mutex mutex_;
+  alignas(utils::Env::CACHE_LINE_SIZE) mutable std::mutex mutex_;
   /// @brief sorted list of bids (descending), key=price, value=size
   absl::btree_map<uint64_t, uint64_t, std::greater<>> bid_map_;
   /// @brief sorted list of offers (ascending), key=price, value=size
   absl::btree_map<uint64_t, uint64_t> ask_map_;
-  //
-  FIX::MDEntryPx e_px_;
-  FIX::MDEntrySize e_sz_;
+  // Temporary variables can share a cache line
+  struct {
+    FIX::MDEntryPx e_px;
+    FIX::MDEntrySize e_sz;
+  } temp_vars_;
   inline void handle_price_level_update(
       auto& bid_ask_map,
       binance::SymbolEnum symbol,
diff --git a/src/core/trade.h b/src/core/trade.h
@@ -3,27 +3,29 @@
 #include <cmath>
 
 #include "../binance/side.h"
+#include "../utils/env.h"
 
 using binance::Side;
 using binance::SideEnum;
 
 namespace core {
 
 /// @brief Binance trade object
-struct Trade {
+struct alignas(utils::Env::CACHE_LINE_SIZE) Trade {
  public:
-  Trade(std::string time,
-        const SideEnum side,
-        const uint64_t px,
+  Trade(const uint64_t px,
         const uint64_t sz,
-        const uint64_t id)
-      : time(std::move(time)), side(side), px(px), sz(sz), id(id) {}
+        const uint64_t id,
+        const SideEnum side,
+        std::array<char, 16> time)
+      : px(px), sz(sz), id(id), side(side), time(time) {}
 
-  std::string time;
-  SideEnum side;
   uint64_t px;
   uint64_t sz;
   uint64_t id;
+  SideEnum side;
+  // 15 characters + newline, e.g. "07:17:50.031794"
+  std::array<char, 16> time;
 };
 
 }  // namespace core
diff --git a/src/main.cpp b/src/main.cpp
@@ -6,6 +6,7 @@
 #include "spdlog/sinks/basic_file_sink.h"
 #include "spdlog/spdlog.h"
 #include "ui/app/ui_app.h"
+#include "utils/env.h"
 #include "utils/threading.h"
 
 int main() {
@@ -19,8 +20,8 @@ int main() {
   // Set a global pattern without the logger name
   spdlog::set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [%t] %v");
   spdlog::flush_every(std::chrono::microseconds(100));
-
   spdlog::info("hello");
+  utils::Env::log_arch();
 
   // Binance market data connectivity
   auto b_conf = binance::Config::from_env();
diff --git a/src/ui/app/ui_app.cpp b/src/ui/app/ui_app.cpp
@@ -77,7 +77,7 @@ void App::start() {
   const ftxui::Component row2 =
       Horizontal({Vertical({wallet_box_.get_component() | flex}) | flex,
                   Vertical({log_box_->get_component() | flex}) | flex});
-  const ftxui::Component root = Vertical({row1 | size(HEIGHT, EQUAL, 20), row2 | flex});
+  const ftxui::Component root = Vertical({row1 | flex, row2 | size(HEIGHT, EQUAL, 6)});
   screen_->loop(root);
 }
 
diff --git a/src/ui/helpers.h b/src/ui/helpers.h
@@ -27,6 +27,13 @@ class Helpers {
   static std::string Pad(const uint64_t input, const size_t width) {
     return Pad(std::to_string(input), width);
   }
+
+  // Helper to pad or truncate a std::array<char, 16> to a fixed width
+  static std::string Pad(const std::array<char, 16>& input, const size_t width) {
+    // Convert array to string (stop at null terminator if present)
+    std::string str(input.data());
+    return Pad(str, width);
+  }
 };
 
 }  // namespace ui
diff --git a/src/ui/log_box/log_box.h b/src/ui/log_box/log_box.h
@@ -8,6 +8,7 @@
 #include <mutex>
 #include <vector>
 
+#include "../../utils/env.h"
 #include "../app/iscreen.h"
 #include "ilog_watcher.h"
 #include "log_file_watcher.h"
@@ -38,8 +39,8 @@ class LogBox {
 
   // log ring-buffer
   std::deque<std::string> log_ring_;
-  static constexpr uint16_t MAX_LINES_ = 100;
-  std::mutex log_ring_mutex_;
+  static inline constexpr uint16_t MAX_LINES_ = 100;
+  alignas(utils::Env::CACHE_LINE_SIZE) std::mutex log_ring_mutex_;
 
   // log-file watcher
   std::unique_ptr<ILogWatcher> log_watcher_;
diff --git a/src/ui/log_box/log_file_watcher.h b/src/ui/log_box/log_file_watcher.h
@@ -15,7 +15,7 @@ class LogFileWatcher : public ILogWatcher, public efsw::FileWatchListener {
   using Callback = std::function<void(std::vector<std::string>)>;
 
  public:
-  static constexpr std::string THREAD_NAME_ = "tradercppuiLOG";
+  static inline constexpr std::string THREAD_NAME_ = "tradercppuiLOG";
 
   explicit LogFileWatcher(std::string directory, std::string filename)
       : directory_(directory), filename_(filename) {
diff --git a/src/ui/order_book_box.h b/src/ui/order_book_box.h
@@ -16,7 +16,7 @@ namespace ui {
 
 class OrderBookBox {
  public:
-  static constexpr std::string THREAD_NAME_ = "tradercppuiBOOK";
+  static inline constexpr std::string THREAD_NAME_ = "tradercppuiBOOK";
   // Constructor: takes a label string
   OrderBookBox(IScreen& screen,
                moodycamel::ConcurrentQueue<std::shared_ptr<const FIX44::Message>>& queue,
diff --git a/src/ui/trade_box.cpp b/src/ui/trade_box.cpp
diff --git a/src/ui/trade_box.h b/src/ui/trade_box.h
diff --git a/src/utils/double.h b/src/utils/double.h
diff --git a/src/utils/env.h b/src/utils/env.h
diff --git a/src/utils/threading.h b/src/utils/threading.h
