From ab4ea22cc1b1cd900876768ad961a2f900e27ba3 Mon Sep 17 00:00:00 2001 From: Yury Kurlykov Date: Tue, 3 Dec 2019 23:38:00 +1000 Subject: [PATCH] Add table file v1 doc --- inc/YeltsinDB/ydb.h | 2 +- table_file.md => table_file_v0.md | 14 +++---- table_file_v1.md | 66 +++++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+), 8 deletions(-) rename table_file.md => table_file_v0.md (84%) create mode 100644 table_file_v1.md diff --git a/inc/YeltsinDB/ydb.h b/inc/YeltsinDB/ydb.h index 8c68934..13652c1 100644 --- a/inc/YeltsinDB/ydb.h +++ b/inc/YeltsinDB/ydb.h @@ -151,7 +151,7 @@ YDB_Error ydb_delete_current_page(YDB_Engine* instance); * * - types.h * - * And in some cases even [table file structure](table_file.md) + * And in some cases even [table file structure](table_file_v0.md) */ #ifdef __cplusplus diff --git a/table_file.md b/table_file_v0.md similarity index 84% rename from table_file.md rename to table_file_v0.md index 314377b..1432606 100644 --- a/table_file.md +++ b/table_file_v0.md @@ -1,4 +1,4 @@ -# Table file structure +# Table file structure (v0) ## Table file version changelog @@ -8,7 +8,7 @@ ### v0.1 Initial version. -## Overall specification +## v0.x specification 1. `TBL!` file signature (4 bytes) **could be `TBL?` if an operation on a table is incompleted** 2. Table file version (2 bytes) @@ -27,7 +27,7 @@ Initial version. In the further time, it's planned to rewrite the file structure, so it's useful to have a version marker. -| 7-4 | 3-0 | +| 15-8 | 7-0 | |---------------|---------------| | Major version | Minor version | @@ -53,10 +53,10 @@ See "Page flags specification" above. A page can be called *free* iff all its rows are deleted. If there is a free page, there actions are being done: -1. Set `DEL` page flag ((6.3) |= FLAG_DEL) -2. If a page is **not** the last one, replace next page offset in the previous page with a value in current page -((previous 6.1) = (6.1)) -3. Put last available free page as the next page ((6.1) = 5) +1. Set `DEL` page flag ((6.1) |= FLAG_DEL) +2. If a page is **not** the first one, replace next page offset in the previous page with a value in current page +((previous 6.2) = (6.2)) +3. Put last available free page as the next page ((6.2) = 5) 4. Set current page offset as the offset to the last available free page ((5) = current_page_offset) ## File signature diff --git a/table_file_v1.md b/table_file_v1.md new file mode 100644 index 0000000..94e584c --- /dev/null +++ b/table_file_v1.md @@ -0,0 +1,66 @@ +# Table file structure (v1) + +## Table file version changelog + +### v1.0 ++ Added previous page offset in page. + +## v1.x specification + +1. `TBL!` file signature (4 bytes) **could be `TBL?` if an operation on a table is incompleted** +2. Table file version (2 bytes) +3. The offset to the first page in a table. (8 bytes) +4. The offset to the last page in a table. (8 bytes) +5. The offset to the last available *free* page (8 bytes) +6. Pages (64 KiB each) + 1. Page flags (1 byte) + 2. Next page offset (8 bytes) **could be 0 if last page** + 3. Previous page offset (8 bytes) **could be 0 if first page** + 4. Row count (2 bytes) + 5. Rows + 1. Row flags (1 byte) + 2. Row data + +## Table file version specification + +In the further time, it's planned to rewrite the file structure, so it's useful to have a version marker. + +| 15-8 | 7-0 | +|---------------|---------------| +| Major version | Minor version | + +That means that the first byte defines major version, and the second one defines minor version. + +If tables with different versions are binary-compatible with each other, their major version must be the same. + +## Page flags specification + +| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +|-----|-----|-----|-----|-----|-----|-----|-----| +| RSV | RSV | RSV | RSV | RSV | RSV | RSV | DEL | + +- **RSV** -- reserved for further usage. +- **DEL** -- free page flag. + +## Row flags specification + +See "Page flags specification" above. + +## Free pages + +A page can be called *free* iff all its rows are deleted. +If there is a free page, there actions are being done: + +1. Set `DEL` page flag ((6.1) |= FLAG_DEL) +2. If a page is **not** the first one, replace next page offset in the previous page with a value in current page +((previous 6.2) = (6.2)) +3. If a page is **not** the last one, replace previous page offset in the next page with a value in current page +((previous 6.3) = (6.3)) +4. Put last available free page as the next page ((6.2) = 5) +5. Set current page offset as the offset to the last available free page ((5) = current_page_offset) + +## File signature + +*Since v0.2* a file signature could be `TBL?`, which signals for incomplete table write operation. +If that signature is detected, the state of a table should be reverted to that it was before failed +transaction. \ No newline at end of file