Ogawa Specification

Intro

Ogawa is a little-endian binary file format created for efficient deferred multi-threaded data reading. It's name is Japanese in origin derived from a common Japanese surname (so as to appear simple and unremarkable), and small river (or stream) meant to invoke the hope of speed and efficiency.

Header

byte 0	byte 1	byte 2	byte 3	byte 4	byte 5	byte 6	byte 7
O	g	a	w	a	FROZEN	VERS0	VERS1
0x4f	0x67	0x61	0x77	0x61	0x00 or 0xff	0x00	0x01

The FROZEN byte is an indicator that the file was properly closed by the Ogawa library when done with all writing operations. It is initially set to 0 when the file is initially opened for writing. 0xff is written to this byte right before it is closed.

VERS0 and VERS1 form the 2 byte Ogawa file format version number. The initial version is and remains to this day, 1.

Bytes 8 to 15 are the 8 byte offset to the first Ogawa Group.

Groups and Data

An Ogawa Group represents a number of offsets to other Ogawa Groups and Ogawa Data. Ogawa Data is a byte stream of a given size.

An Ogawa Group has 2 different forms:

• 8 bytes that are all 0. This represents an empty group that has no children.
• 8 bytes that refer to the number of children, and 8 bytes * that number of children.

The top bit in each child of the 8 byte children determines if that child is another Ogawa Group (if 0), or if it is Ogawa Data (if 1).

The offset to that child Ogawa Group or Ogawa Data is the other 63 bits.

An Ogawa Group can refer to Ogawa Data in 2 different forms:

• 8 bytes where the top bit is 1 and the bottom 63 bits are 0. This is considered to be data of size 0. (or empty data)
• 8 bytes where the top bit is 1 and the bottom 63 bits are not 0. The bottom 63 bits refer to an offset that contains the Ogawa Data as described below.

Non empty Ogawa Data, is made up of 8 bytes for the size, followed by n bytes, where n is that size.