bsistent

[!CAUTION] This is an experimental software. Avoid using this into important systems

Persistent Btree library

Purpose

This library provides a btree that is capable of:

Store integer, strings of variable size, arrays, maps and structs
Reliably serialize and deserialize data in/from disk
Optionally enable in-memory cache with predetermined space
Add and find items
Many features are still under heavy development, such as the ability to update and remove data

Installing bsistent

go get github.com/mylux/bsistent

Using in your code

package main

include (
    "github.com/mylux/bsistent/btree"
    "fmt"
)

type MyDocument struct {
    Name string `bsistent:key,maxSize:200`
    Age int
}

func main () {
    # This creates a btree to store items of type MyDocument at a specific path and a cache for 10 pages.
    
    myBtree := btree.Configuration[MyDocument]().StoragePath("/path/to/data/file").ItemShape(MyDocument{}).CacheSize(10).Grade(5).Make()
    d := MyDocument{Name: "John Doe", Age: 35 }
    myBtree.Add(d)
    retrievedDocument := btree.Find(MyDocument{Name: "John Doe"})
    if d.Age == retrievedDocument.Age {
        fmt.Print("It works")
    }
}

Functions

Configuration

Important: All the configuration functions (except the Make()) return an instance of itself, so it is possible to cascade-call all the configuration methods in the same line

Configuration()

Usage: Configuration[T]()
Returns: *BTConfig[DataType]
Instantiates a configuration object that will afterwards create the btree object. It is a typed method, so although there are no arguments to provide, a type must be provided to make it able to create a btree to store this type of data.

CacheSize(int)

Usage: CacheSize(123)
Returns: *BTConfig[DataType]
Default config: 0
Enables/disables and defines an in-memory cache to reduce the number of accesses to the disk to load the btree pages (nodes).
Setting to 0 disables the cache. The number in the argument is the number of pages
By default, only the root page will stay on memory and all the others will be constantly loaded from the disk. This allows the library to run even if the amount of primary memory is low and the database is huge, with the cost of slower performance.
If the server has memory available, it is interesting to enable as much cache as possible.

Grade(int)

Usage: Grade(123)
Returns: *BTConfig[DataType]
Default config: 500
Defines what is the grade of the Btree. The capacity of each btree page (node) will be grade-1

ItemSize(int)

Usage: ItemSize(123)
Returns: *BTConfig[DataType]
Default config: 64
Defines the size in bytes that each item that will be stored into the btree will have at a maximum. This allows fine-graining on the btree sizing specification. For a facilitation function, check ItemShape()

ItemShape(T)

Usage: ItemShape(item instance of T)
Returns: *BTConfig[DataType]
Another easier way of defining the size of the btree items, providing an instance of the item. bsistent will calculate the proper size based on the provided instance. The item must be the same type as the one defined in the Configuration function type

StoragePath(string)

Usage: StoragePath("string")
Returns: *BTConfig[DataType]
Default config: "/$HOME/.bsistent/bsistent"
Sets the file path where the binary content will be saved

Make()

Usage: Make()
Returns: *BTree[DataType]
Produces the btree with all the configuration specified or the default values

Reset()

Usage: Reset()
Returns: *BTree[DataType]
Erases the data file if there is any data in it.
Caution: This causes all the previous data to be permanently loss.

Btree

Add(T)

Usage: Add(instance of T)
Returns: nothing
Places the item in the correct place into the btree, persists the data and updates the cache if it is set and the item was already previously cached

Find(T)

Usage: Add(instance of T)
Returns: bool, T
Searches for the provided item in the tree returning it if found.
The first return value is a boolean that will be true if the record is found and false when it's not
The second return value will be the item fully loaded from the btree in case it could be found or an empty item (generated by reflect.Zero) otherwise
Important: The value passed in the first (and only) argument of the function Find needs to be an exact copy of the one stored in the tree. In case the value is a struct and the key fields are defined using the bsistent tag, then the item can be only partially complete, having only the key fields with the same content as the one that was previously stored into the tree

Tag keys

Bsistent has a couple of options that can be provided through a bsistent tag that customizes how to work with the user defined type during data serialization and deserialization, item comparison and find operations, consequently.

The tag structure is straightforward:

bsistent:"keyWithoutValue,key:value"

Available tag keys

key

Values: This key has no value
Description: Defines that field as a search key. Multiple fields can be defined as search keys and an item will only be matched in the results if all those key fields are equal (binary comparison).

maxSize

Values: integer number
Description: Defines the size of this field in bytes. This is (only) useful for varying type variables, such as arrays or strings, as those types don't have hardcoded sizes in go. Any value smaller than maxSize of the same type of the field can be stored, but bsistent will reserve the maxSize number of bytes in the persistence layer. The field value to the end user will be unchanged and this storage characteristic will mostly go unnoticed.

# Packages

# README