Pre-Relase 🥇

.github/workflows/main.yml

@@ -18,14 +18,12 @@ jobs:
 
     - name: Install Zig
       run: |
-        wget https://ziglang.org/builds/zig-linux-x86_64-0.14.0-dev.1951+857383689.tar.xz
-        tar -xf zig-linux-x86_64-0.14.0-dev.1951+857383689.tar.xz
-        sudo mv zig-linux-x86_64-0.14.0-dev.1951+857383689 $HOME/zig
+        wget https://ziglang.org/builds/zig-linux-x86_64-0.14.0-dev.2643+fb43e91b2.tar.xz
+        tar -xf zig-linux-x86_64-0.14.0-dev.2643+fb43e91b2.tar.xz
+        sudo mv zig-linux-x86_64-0.14.0-dev.2643+fb43e91b2 $HOME/zig
         $HOME/zig/zig version
 
     - name: Build and test
       run: |
         mkdir dirty 
-        $HOME/zig/zig build
-        $HOME/zig/zig build test
-        $HOME/zig/zig test src/cursor_test.zig
+        $HOME/zig/zig test src/root.zig

README.md

@@ -1 +1,53 @@
-# boltdb-zig
+# boltdb-zig
+
+A pure Zig implementation of BoltDB, an embedded key/value database.
+
+## Overview
+
+boltdb-zig is a Zig port of the original [BoltDB](https://github.com/boltdb/bolt), which is a simple yet powerful embedded key/value database written in Go. It provides a consistent and ACID-compliant data store with the following features:
+
+- Pure Zig implementation
+- Single file backend
+- ACID transactions
+- Lock-free MVCC
+- Nested buckets
+
+## Status
+
+🚧 This project is currently under development.
+
+## Usage
+
+```zig
+# zig fetch --save git+https://github.com/laohanlinux/boltdb-zig.git
+```
+
+import the library in your build.zig.zon file: [link](example/build.zig.zon)
+
+```
+const boltdbDep = b.dependency("boltdb-zig", .{
+    .target = target,
+    .optimize = optimize,
+});
+
+const exe = b.addExecutable(.{
+    .name = "example",
+    .root_source_file = b.path("src/main.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+
+exe.root_module.addImport("boltdb", boltdbDep.module("boltdb"));
+```
+
+How use?
+[link](example/src/main.zig)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- Original [BoltDB](https://github.com/boltdb/bolt)
+

book/design.md

@@ -266,3 +266,73 @@ func (b *Bucket) write() []byte {
 |bucketHeader|page|
 ```
 
+## 事务管理
+
+### Example
+
+- 初始化状态
+
+```
+tid = 10,
+```
+
+- 创建2个读事务
+
+第一个读事务
+
+```
+tid = 10, // 读事务，不会递增事务id
+ReadTxPtr = 0x100, // 读事务的指针
+```
+
+第二个读事务
+
+```
+tid = 10, // 读事务，不会递增事务id
+ReadTxPtr = 0x101, // 读事务的指针
+```
+
+假设此时，他们都引用了同一个page，pid = 89
+
+- 创建一个写事务
+
+```
+tid = 11,
+WriteTxPtr = 0x102, // 写事务的指针
+```
+
+该事务也引用了同一个page，pid = 89。
+
+
+*此时*，事务管理器中，有3个事务，2个读事务，1个写事务。
+
+Bolt如何处理？
+
+一种简单的解决办法是：
+``` 
+### Page生命周期管理
+
+对于上述场景中的page 89，Bolt采用以下策略管理其生命周期：
+
+1. **引用计数**
+- 每个page维护内部引用计数
+- 当前page 89有3个引用（2个读事务 + 1个写事务）
+- 引用计数确保页面在仍被使用时不会被释放
+
+2. **写时复制（Copy-on-Write）**
+- 写事务修改page 89时会创建新副本
+- 读事务继续使用原始page 89
+- 写事务使用新的page副本
+- 原始page 89会保留到所有读事务完成
+
+3. **页面释放**
+- 读事务完成时递减引用计数
+- 只有引用计数为0时才释放页面
+- 写事务提交后，新页面版本对后续事务可见
+
+这种机制确保了:
+- 读事务的数据一致性
+- 写事务的隔离性
+- 高效的内存管理
+```
+

build.zig

@@ -15,6 +15,11 @@ pub fn build(b: *std.Build) void {
     // set a preferred release mode, allowing the user to decide how to optimize.
     const optimize = b.standardOptimizeOption(.{});
 
+    // Create module
+    _ = b.addModule("boltdb", .{
+        .root_source_file = b.path("src/namespace.zig"),
+    });
+
     const lib = b.addStaticLibrary(.{
         .name = "boltdb-zig",
         // In this case the main source file is merely a path, however, in more
@@ -23,7 +28,6 @@ pub fn build(b: *std.Build) void {
         .target = target,
         .optimize = optimize,
     });
-
     // This declares intent for the library to be installed into the standard
     // location when the user invokes the "install" step (the default step when
     // running `zig build`).

build.zig.zon

@@ -14,48 +14,6 @@
     // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
     // Once all dependencies are fetched, `zig build` no longer requires
     // internet connectivity.
-    .dependencies = .{
-        // .string = .{
-        //     .url = "https://github.com/JakubSzark/zig-string/archive/refs/heads/master.tar.gz",
-        //     .hash = "1220fc05a513524010e93b4734392c728d5364fb6669b33cec9dae7225d56a5eedde"
-        //     //the correct hash will be suggested by zig
-        // }
-        // See `zig fetch --save <url>` for a command-line interface for adding dependencies.
-        //.example = .{
-        //    // When updating this field to a new URL, be sure to delete the corresponding
-        //    // `hash`, otherwise you are communicating that you expect to find the old hash at
-        //    // the new URL.
-        //    .url = "https://example.com/foo.tar.gz",
-        //
-        //    // This is computed from the file contents of the directory of files that is
-        //    // obtained after fetching `url` and applying the inclusion rules given by
-        //    // `paths`.
-        //    //
-        //    // This field is the source of truth; packages do not come from a `url`; they
-        //    // come from a `hash`. `url` is just one of many possible mirrors for how to
-        //    // obtain a package matching this `hash`.
-        //    //
-        //    // Uses the [multihash](https://multiformats.io/multihash/) format.
-        //    .hash = "...",
-        //
-        //    // When this is provided, the package is found in a directory relative to the
-        //    // build root. In this case the package's hash is irrelevant and therefore not
-        //    // computed. This field and `url` are mutually exclusive.
-        //    .path = "foo",
-
-        //    // When this is set to `true`, a package is declared to be lazily
-        //    // fetched. This makes the dependency only get fetched if it is
-        //    // actually used.
-        //    .lazy = false,
-        //},
-    },
-
-    // Specifies the set of files and directories that are included in this package.
-    // Only files and directories listed here are included in the `hash` that
-    // is computed for this package.
-    // Paths are relative to the build root. Use the empty string (`""`) to refer to
-    // the build root itself.
-    // A directory listed here means that all files within, recursively, are included.
     .paths = .{
         // This makes *all* files, recursively, included in this package. It is generally
         // better to explicitly list the files and directories instead, to insure that

example/build.zig

@@ -0,0 +1,98 @@
+const std = @import("std");
+
+// Although this function looks imperative, note that its job is to
+// declaratively construct a build graph that will be executed by an external
+// runner.
+pub fn build(b: *std.Build) void {
+    // Standard target options allows the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
+    const target = b.standardTargetOptions(.{});
+
+    // Standard optimization options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
+    // set a preferred release mode, allowing the user to decide how to optimize.
+    const optimize = b.standardOptimizeOption(.{});
+
+    const lib = b.addStaticLibrary(.{
+        .name = "example",
+        // In this case the main source file is merely a path, however, in more
+        // complicated build scripts, this could be a generated file.
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    // This declares intent for the library to be installed into the standard
+    // location when the user invokes the "install" step (the default step when
+    // running `zig build`).
+    b.installArtifact(lib);
+    const boltdbDep = b.dependency("boltdb-zig", .{
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const exe = b.addExecutable(.{
+        .name = "example",
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    exe.root_module.addImport("boltdb", boltdbDep.module("boltdb"));
+    // This declares intent for the executable to be installed into the
+    // standard location when the user invokes the "install" step (the default
+    // step when running `zig build`).
+    b.installArtifact(exe);
+
+    // This *creates* a Run step in the build graph, to be executed when another
+    // step is evaluated that depends on it. The next line below will establish
+    // such a dependency.
+    const run_cmd = b.addRunArtifact(exe);
+
+    // By making the run step depend on the install step, it will be run from the
+    // installation directory rather than directly from within the cache directory.
+    // This is not necessary, however, if the application depends on other installed
+    // files, this ensures they will be present and in the expected location.
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    // This allows the user to pass arguments to the application in the build
+    // command itself, like this: `zig build run -- arg1 arg2 etc`
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    // This creates a build step. It will be visible in the `zig build --help` menu,
+    // and can be selected like this: `zig build run`
+    // This will evaluate the `run` step rather than the default, which is "install".
+    const run_step = b.step("run", "Run the app");
+    run_step.dependOn(&run_cmd.step);
+
+    // Creates a step for unit testing. This only builds the test executable
+    // but does not run it.
+    const lib_unit_tests = b.addTest(.{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    lib_unit_tests.root_module.addImport("boltdb", boltdbDep.module("boltdb"));
+
+    const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);
+
+    const exe_unit_tests = b.addTest(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    exe_unit_tests.root_module.addImport("boltdb", boltdbDep.module("boltdb"));
+
+    const run_exe_unit_tests = b.addRunArtifact(exe_unit_tests);
+
+    // Similar to creating the run step earlier, this exposes a `test` step to
+    // the `zig build --help` menu, providing a way for the user to request
+    // running the unit tests.
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_lib_unit_tests.step);
+    test_step.dependOn(&run_exe_unit_tests.step);
+}

example/build.zig.zon

@@ -0,0 +1,39 @@
+.{
+    // This is the default name used by packages depending on this one. For
+    // example, when a user runs `zig fetch --save <url>`, this field is used
+    // as the key in the `dependencies` table. Although the user can choose a
+    // different name, most users will stick with this provided value.
+    //
+    // It is redundant to include "zig" in this name because it is already
+    // within the Zig package namespace.
+    .name = "example",
+
+    // This is a [Semantic Version](https://semver.org/).
+    // In a future version of Zig it will be used for package deduplication.
+    .version = "0.0.0",
+
+    // This field is optional.
+    // This is currently advisory only; Zig does not yet do anything
+    // with this value.
+    //.minimum_zig_version = "0.11.0",
+
+    // This field is optional.
+    // Each dependency must either provide a `url` and `hash`, or a `path`.
+    // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
+    // Once all dependencies are fetched, `zig build` no longer requires
+    // internet connectivity.
+    .dependencies = .{
+        .@"boltdb-zig" = .{
+            .url = "git+https://github.com/laohanlinux/boltdb-zig.git/?ref=align#f2ae8cd9a8d4396fec3fbbed3adbd9a14e0fa1a3",
+            .hash = "12203cc7a802ae6cd01c6b856ff96ddfe26cb9612533ca116a0e30178d5251e173bd",
+        },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        // For example...
+        //"LICENSE",
+        //"README.md",
+    },
+}