Merge pull request #18 from bbalouki/bbs-dev

bug fix

Author: juniorep

examples/CMakeLists.txt

@@ -1,14 +1,14 @@
 cmake_minimum_required(VERSION 3.20)
 
-add_executable(parser_example parser/main.cpp)
+add_executable(parser_example parser/parser_example.cpp)
 
 target_link_libraries(
     parser_example PRIVATE
     itch::itch
     warnings::strict
 )
 
-add_executable(order_book_example order_book/main.cpp)
+add_executable(order_book_example order_book/order_book_example.cpp)
 
 target_link_libraries(
     order_book_example PRIVATE

examples/order_book/main.cpp

@@ -0,0 +1,36 @@
+#include <chrono>
+#include <fstream>
+#include <iostream>
+#include <vector>
+
+#include "itch/order_book.hpp"
+#include "itch/parser.hpp"
+
+
+int main(int argc, char* argv[]) {
+    if (argc != 2) {
+        std::cerr << "Usage: " << argv[0] << " <itch_file>\n";
+        return 1;
+    }
+
+    std::ifstream file(argv[1], std::ios::binary);
+    if (!file) {
+        std::cerr << "Error: Could not open file " << argv[1] << "\n";
+        return 1;
+    }
+
+    itch::Parser         parser;
+    itch::LimitOrderBook order_book;
+
+    try {
+        auto processor = [&](auto&& msg) { order_book.process(msg); };
+        parser.parse(file, processor);
+        order_book.print(std::cout);
+
+    } catch (const std::exception& e) {
+        std::cerr << "An error occurred: " << e.what() << "\n";
+        return 1;
+    }
+
+    return 0;
+}

examples/order_book/order_book_example.cpp

@@ -16,13 +16,20 @@ namespace itch {
 
 struct PriceLevel;
 
-// Represent a single order in the order book.
+/**
+ * @struct Order
+ * @brief Represents a single resting order within the Limit Order Book.
+ *
+ * Encapsulates all necessary state data for an order, including its unique
+ * reference number, side (Buy/Sell), quantity, and price. It also maintains
+ * a pointer to its parent PriceLevel for efficient traversal.
+ */
 struct Order {
-    uint64_t    order_reference_number;
-    char        buy_sell_indicator;
-    uint32_t    shares;
-    uint32_t    price;
-    PriceLevel* level;
+    uint64_t order_reference_number;  ///< Unique identifier assigned to the order by the exchange.
+    char     buy_sell_indicator;      ///< 'B' for Buy, 'S' for Sell.
+    uint32_t shares;                  ///< Current quantity of shares available in this order.
+    uint32_t price;                   ///< Limit price of the order.
+    PriceLevel* level;                ///< Pointer to the price level containing this order.
 
     Order(uint64_t ref_num, char side, uint32_t shrs, uint32_t prc)
         : order_reference_number{ref_num},
@@ -32,67 +39,115 @@ struct Order {
           level{nullptr} {}
 };
 
+/// Iterator type for navigating the list of orders within a price level.
 using OrderIt = std::list<std::shared_ptr<Order>>::iterator;
 
-// Represent a price level in the order book.
-// Contains a list of orders at that price, in time priority.
+/**
+ * @struct PriceLevel
+ * @brief Represents a specific price node in the order book.
+ *
+ * Maintains a queue of orders at a specific price, enforcing Time-Priority
+ * (FIFO) execution. It tracks the aggregate share volume for this level.
+ */
 struct PriceLevel {
-    uint32_t                          total_shares{0};
-    std::list<std::shared_ptr<Order>> orders;
+    uint32_t total_shares{0};                  ///< Aggregate volume of shares at this price.
+    std::list<std::shared_ptr<Order>> orders;  ///< FIFO queue of orders.
 
+    /**
+     * @brief Appends an order to the end of the queue (Time priority).
+     * @param order Shared pointer to the order to add.
+     */
     void add_order(std::shared_ptr<Order> order);
+
+    /**
+     * @brief Removes a specific order from the queue.
+     * @param order_it Iterator pointing to the order to remove.
+     */
     void remove_order(OrderIt order_it);
 };
 
 /**
  * @class LimitOrderBook
- * @brief A class that represents and maintains a limit order book for a single stock.
+ * @brief Manages the state of a limit order book for a specific financial instrument.
+ *
+ * The LimitOrderBook ingests raw Nasdaq ITCH 5.0 messages and reconstructs the
+ * full depth of market. It supports standard order lifecycle events including
+ * addition, execution, cancellation, deletion, and replacement.
  *
- * The LimitOrderBook processes ITCH 5.0 messages to build and maintain the
- * state of the order book. It handles adding, executing, canceling, deleting,
- * and replacing orders.
+ * @note This implementation uses `std::map` for price levels to ensure
+ * keys (prices) are always sorted, allowing for O(log n) insertion and deletion
+ * of price levels, and O(1) access to the best bid/ask.
  */
 class LimitOrderBook {
    public:
     /**
-     * @brief Processes a single ITCH message and updates the order book accordingly.
-     * @param message The ITCH message to process.
+     * @brief Dispatches and processes a generic ITCH message.
+     *
+     * Identifies the specific type within the `Message` variant and routes it
+     * to the appropriate internal handler to update the book state.
+     *
+     * @param message The parsed ITCH message variant.
      */
     void process(const Message& message);
 
     /**
-     * @brief Prints the current state of the order book to the given output stream.
-     * @param out The output stream to print to.
+     * @brief Visualizes the current state of the order book to an output stream.
+     *
+     * Prints the best Ask and Bid levels formatted in a table.
+     *
+     * @param out The output stream (e.g., std::cout) to write to.
+     * @param delay_ms Optional delay in milliseconds between printing each line.
+     *                 Useful for slowing down output during debugging or replays
+     *                 to create an animation effect. Defaults to 0 (no delay).
      */
     void print(std::ostream& out, unsigned int delay_ms = 0) const;
 
-    // Type aliases for the bid and ask maps.
+    // Type aliases for the bid and ask maps (sorted containers).
     using BidMap = std::map<uint32_t, PriceLevel, std::greater<uint32_t>>;
     using AskMap = std::map<uint32_t, PriceLevel, std::less<uint32_t>>;
 
-    const BidMap&        get_bids() const { return m_bids; }
-    const AskMap&        get_asks() const { return m_asks; }
+    /**
+     * @return A reference to the map of active Bids, sorted descending by price.
+     */
+    const BidMap& get_bids() const { return m_bids; }
+
+    /**
+     * @return A reference to the map of active Asks, sorted ascending by price.
+     */
+    const AskMap& get_asks() const { return m_asks; }
+
+    /// Set of message type characters that affect the book state.
     const std::set<char> book_messages{'A', 'F', 'E', 'C', 'X', 'D', 'U'};
 
    private:
-    BidMap                      m_bids;    ///< Map of bid price levels (price -> PriceLevel)
-    AskMap                      m_asks;    ///< Map of ask price levels (price -> PriceLevel)
-    std::map<uint64_t, OrderIt> m_orders;  ///< Map of orders by reference number
+    BidMap                      m_bids;  ///< Ask price levels (Price -> Level). Sorted Low-to-High.
+    AskMap                      m_asks;  ///< Bid price levels (Price -> Level). Sorted High-to-Low.
+    std::map<uint64_t, OrderIt> m_orders;  ///< Hash map for O(1) order lookup by Reference Number.
 
-    // Handler methods for specific message types
+    // Message Handlers
     void handle_message(const AddOrderMessage& msg);
     void handle_message(const AddOrderMPIDAttributionMessage& msg);
     void handle_message(const OrderExecutedMessage& msg);
     void handle_message(const OrderExecutedWithPriceMessage& msg);
     void handle_message(const OrderCancelMessage& msg);
     void handle_message(const OrderDeleteMessage& msg);
     void handle_message(const OrderReplaceMessage& msg);
-    // Generic handler for message types we don't care about
+
+    // Generic handler/sink for message types that do not impact book state.
     template <typename T>
-    void handle_message(const T& msg) { /* Ignore */ }
+    void handle_message(const T& /* msg */) { /* No-op for irrelevant messages */ }
 
-    // Helper methods
+    /**
+     * @brief Creates an Order object and inserts it into the appropriate PriceLevel.
+     */
     void add_order(uint64_t order_ref, char side, uint32_t shares, uint32_t price);
+
+    /**
+     * @brief Reduces shares from an order or removes it entirely if fully depleted.
+     *
+     * @param order_ref The unique reference number of the target order.
+     * @param canceled_shares The number of shares to remove.
+     */
     void remove_order(uint64_t order_ref, uint32_t canceled_shares);
 };