From 151b1f5a7768dce90e10706db5d4027f93366bba Mon Sep 17 00:00:00 2001 From: Iwan BK Date: Fri, 14 Feb 2025 10:43:50 +0700 Subject: [PATCH] refcount tech spec --- docs/refcount.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/refcount.md diff --git a/docs/refcount.md b/docs/refcount.md new file mode 100644 index 0000000..a8e6505 --- /dev/null +++ b/docs/refcount.md @@ -0,0 +1,39 @@ +# Reference Counting (Refcount) + +Refcount adds reference counting to data blocks. + +The idea is that different objects might share the same data blocks. +When a data block is used by an object, its refcount is increased by one. +When an object stops using the data block, the refcount is decreased by one. +When the refcount reaches zero, the data block can be deleted. + +`There can be some data leakage, but never data loss`. This means that, in case of some failures, it is acceptable to not decrease the refcount. However, it is crucial to never fail to increase the refcount, as this can lead to data loss. + +## Test Plan + +**Normal cases:** + +- Creating a new object will set `refcount` to 1. +- If the same key reuses the block, `refcount` will not be increased. +- If a new key reuses the block, `refcount` will be increased by one. +- Deleting the object will reduce the `refcount` value. +- When the `refcount` value reaches zero, the object must be deleted. + +**Failure cases:** +- when writing/reusing block, failed to write the metadata or increase the `refcount` + + -> it is not allowed to happen, the writing/reusing must be failed, data loss could happend + +- when writing the block, `refcount` already increased but failed to write the block to the underlying storage. + + -> it is OK, data leakage could happen + +- when deleting a block, failed to reduce the `refcount` or delete the metadata + + -> it is OK, data leakage could happen + +- when deleting a block, failed to delete from the underlying storage + + -> it is OK, data leakage happened + +For the above failure cases, the tests only mandatory to be implemented for the cases that not allowed to happen \ No newline at end of file