From 58346b9e29b38481544ad91814760d557913283e Mon Sep 17 00:00:00 2001
From: krad <krad@fb.com>
Date: Mon, 6 Apr 2015 18:15:00 -0700
Subject: [PATCH] Log writer record format doc.

Summary: Added a ASCII doodle to represent the log writer format.

Test Plan: None

Reviewers: sdong

CC: leveldb

Task ID: 6179896

Blame Rev:
---
 db/log_reader.h |  6 ++++++
 db/log_writer.h | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/db/log_reader.h b/db/log_reader.h
index 81d334da29..a7cf45b4a0 100644
--- a/db/log_reader.h
+++ b/db/log_reader.h
@@ -22,6 +22,12 @@ using std::unique_ptr;
 
 namespace log {
 
+/**
+ * Reader is a general purpose log stream reader implementation. The actual job
+ * of reading from the device is implemented by the SequentialFile interface.
+ *
+ * Please see Writer for details on the file and record layout.
+ */
 class Reader {
  public:
   // Interface for reporting errors.
diff --git a/db/log_writer.h b/db/log_writer.h
index d7b7afff09..46226ec27a 100644
--- a/db/log_writer.h
+++ b/db/log_writer.h
@@ -22,6 +22,40 @@ using std::unique_ptr;
 
 namespace log {
 
+/**
+ * Writer is a general purpose log stream writer. It provides an append-only
+ * abstraction for writing data. The details of the how the data is written is
+ * handled by the WriteableFile sub-class implementation.
+ *
+ * File format:
+ *
+ * File is broken down into variable sized records. The format of each record
+ * is described below.
+ *       +-----+-------------+--+----+----------+------+-- ... ----+
+ * File  | r0  |        r1   |P | r2 |    r3    |  r4  |           |
+ *       +-----+-------------+--+----+----------+------+-- ... ----+
+ *       <--- kBlockSize ------>|<-- kBlockSize ------>|
+ *  rn = variable size records
+ *  P = Padding
+ *
+ * Data is written out in kBlockSize chunks. If next record does not fit
+ * into the space left, the leftover space will be padded with \0.
+ *
+ * Record format:
+ *
+ * +---------+-----------+-----------+--- ... ---+
+ * |CRC (4B) | Size (2B) | Type (1B) | Payload   |
+ * +---------+-----------+-----------+--- ... ---+
+ *
+ * CRC = 32bit hash computed over the payload using CRC
+ * Size = Length of the payload data
+ * Type = Type of record
+ *        (kZeroType, kFullType, kFirstType, kLastType, kMiddleType )
+ *        The type is used to group a bunch of records together to represent
+ *        blocks that are larger than kBlockSize
+ * Payload = Byte stream as long as specified by the payload size
+ *
+ */
 class Writer {
  public:
   // Create a writer that will append data to "*dest".