BinaryLog: add rotation callback (#71)

Author: eeiaao

docs/reference/api/replay/binary_log_writer.md

@@ -3,16 +3,24 @@
 `BinaryLogWriter` writes market data to binary log segments. It handles segment rotation, compression, indexing, and CRC checksums.
 
 ```cpp
+// Callback for custom segment naming on rotation
+using RotationCallback = std::filesystem::path (*)(
+    void* user_data,
+    const std::filesystem::path& output_dir,
+    uint32_t segment_number);
+
 struct WriterConfig {
   std::filesystem::path output_dir;
-  std::string output_filename;              // Optional: override generated name
+  std::string output_filename;              // Optional: first segment name
   uint64_t max_segment_bytes{256ull << 20}; // 256 MB default
   uint64_t buffer_size{64ull << 10};        // 64 KB buffer
   uint8_t exchange_id{0};
   bool sync_on_rotate{true};
   bool create_index{true};
   uint16_t index_interval{1000};            // Events per index entry
   CompressionType compression{CompressionType::None};
+  RotationCallback rotation_callback{nullptr};  // Custom naming on rotation
+  void* rotation_user_data{nullptr};            // User data for callback
 };
 
 class BinaryLogWriter {
@@ -44,14 +52,16 @@ public:
 | Field | Default | Description |
 |-------|---------|-------------|
 | `output_dir` | - | Directory for segment files. |
-| `output_filename` | - | Optional fixed filename (disables rotation). |
+| `output_filename` | - | Optional filename for first segment. |
 | `max_segment_bytes` | 256 MB | Maximum segment size before rotation. |
 | `buffer_size` | 64 KB | Internal write buffer size. |
 | `exchange_id` | 0 | Exchange identifier in segment header. |
 | `sync_on_rotate` | true | Sync to disk on segment rotation. |
 | `create_index` | true | Build seek index in segments. |
 | `index_interval` | 1000 | Events between index entries. |
 | `compression` | None | Compression type (`None` or `LZ4`). |
+| `rotation_callback` | nullptr | Custom callback for segment naming on rotation. |
+| `rotation_user_data` | nullptr | User data passed to rotation callback. |
 
 ## Methods
 
@@ -107,6 +117,47 @@ writer.flush();
 writer.close();
 ```
 
+## Custom Rotation Callback
+
+By default, rotated segments use timestamp-based names. To customize naming:
+
+```cpp
+// Context for the callback
+struct MyContext {
+  std::string prefix;
+  int sequence{1};
+};
+
+// Callback function (must be a plain function, not a lambda with captures)
+std::filesystem::path my_rotation_cb(
+    void* user_data,
+    const std::filesystem::path& output_dir,
+    uint32_t segment_number)
+{
+  auto* ctx = static_cast<MyContext*>(user_data);
+  std::ostringstream fname;
+  fname << ctx->prefix << "_" << std::setfill('0') << std::setw(3)
+        << (ctx->sequence + segment_number - 1) << ".floxlog";
+  return output_dir / fname.str();
+}
+
+// Usage
+MyContext ctx{"2025-01-15", 1};
+
+replay::WriterConfig config{
+  .output_dir = "/data/market",
+  .output_filename = "2025-01-15_001.floxlog",  // First segment
+  .max_segment_bytes = 256ull << 20,
+  .rotation_callback = my_rotation_cb,
+  .rotation_user_data = &ctx,  // Must outlive writer!
+};
+
+replay::BinaryLogWriter writer(config);
+// When segment rotates, callback generates "2025-01-15_002.floxlog", etc.
+```
+
+**Important:** The `rotation_user_data` pointer must remain valid for the lifetime of the writer.
+
 ## Notes
 
 * Thread-safe via internal mutex.

include/flox/replay/writers/binary_log_writer.h

@@ -21,17 +21,26 @@
 namespace flox::replay
 {
 
+using RotationCallback = std::filesystem::path (*)(void* user_data,
+                                                   const std::filesystem::path& output_dir,
+                                                   uint32_t segment_number);
+
 struct WriterConfig
 {
   std::filesystem::path output_dir;
-  std::string output_filename;  // If set, use this filename instead of generating one
+  std::string output_filename;  // If set, use this filename for first segment
   uint64_t max_segment_bytes{256ull << 20};
   uint64_t buffer_size{64ull << 10};
   uint8_t exchange_id{0};
   bool sync_on_rotate{true};
   bool create_index{true};
   uint16_t index_interval{kDefaultIndexInterval};
   CompressionType compression{CompressionType::None};
+
+  /// Optional callback for custom segment naming on rotation.
+  /// If not set, rotated segments use timestamp-based names.
+  RotationCallback rotation_callback{nullptr};
+  void* rotation_user_data{nullptr};
 };
 
 struct WriterStats
@@ -76,7 +85,7 @@ class BinaryLogWriter
   void updateSegmentHeader();
   void writeIndex();
   void closeInternal();
-  std::filesystem::path generateSegmentPath() const;
+  std::filesystem::path generateSegmentPath();
 
   bool isCompressed() const { return _config.compression != CompressionType::None; }
 
@@ -89,6 +98,7 @@ class BinaryLogWriter
 
   SegmentHeader _segment_header{};
   uint64_t _segment_bytes{0};
+  uint32_t _segment_number{0};  // current segment number (1-based after first open)
   bool _header_written{false};
 
   std::vector<IndexEntry> _index_entries;

src/replay/binary_log_writer.cpp

@@ -68,13 +68,24 @@ BinaryLogWriter& BinaryLogWriter::operator=(BinaryLogWriter&& other) noexcept
   return *this;
 }
 
-std::filesystem::path BinaryLogWriter::generateSegmentPath() const
+std::filesystem::path BinaryLogWriter::generateSegmentPath()
 {
-  if (!_config.output_filename.empty())
+  ++_segment_number;
+
+  // First segment: use output_filename if provided
+  if (_segment_number == 1 && !_config.output_filename.empty())
   {
     return _config.output_dir / _config.output_filename;
   }
 
+  // Use rotation callback if provided
+  if (_config.rotation_callback)
+  {
+    return _config.rotation_callback(_config.rotation_user_data, _config.output_dir,
+                                     _segment_number);
+  }
+
+  // Default: timestamp-based naming
   using namespace std::chrono;
   auto now = system_clock::now();
   auto ns = duration_cast<nanoseconds>(now.time_since_epoch()).count();