Update within() to make caching optional

Author: marselester

README.md

@@ -203,3 +203,80 @@ Lookups Per Second (avg):1315986.2950186788
 ```
 
 </details>
+
+Use `within()` to iterate over all networks in the database using
+a cache to avoid re-decoding adjacent networks that share the same record.
+
+```zig
+var cache: maxminddb.Cache(maxminddb.any.Value) = .{};
+defer cache.deinit();
+
+var it = try db.within(
+    allocator,
+    maxminddb.any.Value,
+    maxminddb.Network.all_ipv6,
+    .{ .cache = &cache },
+);
+defer it.deinit();
+
+while (try it.next()) |item| {
+    std.debug.print("{f} {f}\n", .{item.network, item.value});
+}
+```
+
+Without a cache each result owns its memory and must be freed with `item.deinit()`.
+
+Here are reference results on Apple M2 Pro (full GeoLite2-City scan using `any.Value`):
+
+| Benchmark    | Records/sec |
+|---           |---          |
+| No cache     | ~1,235,000  |
+| Cache (16)   | ~2,900,000  |
+
+<details>
+
+<summary>no cache (any.Value)</summary>
+
+```sh
+$ for i in $(seq 1 10); do
+    zig build benchmark_within -Doptimize=ReleaseFast -- GeoLite2-City.mmdb \
+      2>&1 | grep 'Records Per Second'
+  done
+
+Records Per Second: 1216758.945145436
+Records Per Second: 1238440.9772222256
+Records Per Second: 1234710.6362391203
+Records Per Second: 1229527.4688849829
+Records Per Second: 1243478.3908140333
+Records Per Second: 1226863.3718734735
+Records Per Second: 1240073.3248202254
+Records Per Second: 1247541.1528026997
+Records Per Second: 1230510.441029532
+Records Per Second: 1246311.587919839
+```
+
+</details>
+
+<details>
+
+<summary>cache (any.Value)</summary>
+
+```sh
+$ for i in $(seq 1 10); do
+    zig build benchmark_within_cache -Doptimize=ReleaseFast -- GeoLite2-City.mmdb \
+      2>&1 | grep 'Records Per Second'
+  done
+
+Records Per Second: 2847560.3756875996
+Records Per Second: 2925388.867798729
+Records Per Second: 2919203.9046571665
+Records Per Second: 2814410.555872645
+Records Per Second: 2933972.04386147
+Records Per Second: 2900700.06160036
+Records Per Second: 2922279.338699886
+Records Per Second: 2862525.847598088
+Records Per Second: 2916760.542913819
+Records Per Second: 2908245.98918392
+```
+
+</details>

benchmarks/within.zig

@@ -0,0 +1,59 @@
+const std = @import("std");
+const maxminddb = @import("maxminddb");
+
+const default_db_path: []const u8 = "GeoLite2-City.mmdb";
+
+pub fn main() !void {
+    const allocator = std.heap.smp_allocator;
+
+    const args = try std.process.argsAlloc(allocator);
+    defer std.process.argsFree(allocator, args);
+
+    var db_path: []const u8 = default_db_path;
+    if (args.len > 1) db_path = args[1];
+
+    std.debug.print("Benchmarking with:\n", .{});
+    std.debug.print("  Database: {s}\n", .{db_path});
+    std.debug.print("Opening database...\n", .{});
+
+    var open_timer = try std.time.Timer.start();
+    var db = try maxminddb.Reader.mmap(allocator, db_path, .{});
+    defer db.close();
+    const open_time_ms = @as(f64, @floatFromInt(open_timer.read())) /
+        @as(f64, @floatFromInt(std.time.ns_per_ms));
+    std.debug.print("Database opened successfully in {d} ms. Type: {s}\n", .{
+        open_time_ms,
+        db.metadata.database_type,
+    });
+
+    const network = if (db.metadata.ip_version == 4)
+        maxminddb.Network.all_ipv4
+    else
+        maxminddb.Network.all_ipv6;
+
+    std.debug.print("Starting benchmark...\n", .{});
+    var timer = try std.time.Timer.start();
+
+    var it = try db.within(allocator, maxminddb.any.Value, network, .{});
+    defer it.deinit();
+
+    var n: usize = 0;
+    while (try it.next()) |item| {
+        n += 1;
+        item.deinit();
+    }
+
+    const elapsed_ns = timer.read();
+    const elapsed_s = @as(f64, @floatFromInt(elapsed_ns)) /
+        @as(f64, @floatFromInt(std.time.ns_per_s));
+
+    const records_per_second = if (elapsed_s > 0)
+        @as(f64, @floatFromInt(n)) / elapsed_s
+    else
+        0.0;
+
+    std.debug.print("\n--- Benchmark Finished ---\n", .{});
+    std.debug.print("Records:            {d}\n", .{n});
+    std.debug.print("Elapsed Time:       {d} s\n", .{elapsed_s});
+    std.debug.print("Records Per Second: {d}\n", .{records_per_second});
+}

benchmarks/within_cache.zig

@@ -0,0 +1,66 @@
+const std = @import("std");
+const maxminddb = @import("maxminddb");
+
+const default_db_path: []const u8 = "GeoLite2-City.mmdb";
+
+pub fn main() !void {
+    const allocator = std.heap.smp_allocator;
+
+    const args = try std.process.argsAlloc(allocator);
+    defer std.process.argsFree(allocator, args);
+
+    var db_path: []const u8 = default_db_path;
+    if (args.len > 1) db_path = args[1];
+
+    std.debug.print("Benchmarking with:\n", .{});
+    std.debug.print("  Database: {s}\n", .{db_path});
+    std.debug.print("Opening database...\n", .{});
+
+    var open_timer = try std.time.Timer.start();
+    var db = try maxminddb.Reader.mmap(allocator, db_path, .{});
+    defer db.close();
+    const open_time_ms = @as(f64, @floatFromInt(open_timer.read())) /
+        @as(f64, @floatFromInt(std.time.ns_per_ms));
+    std.debug.print("Database opened successfully in {d} ms. Type: {s}\n", .{
+        open_time_ms,
+        db.metadata.database_type,
+    });
+
+    const network = if (db.metadata.ip_version == 4)
+        maxminddb.Network.all_ipv4
+    else
+        maxminddb.Network.all_ipv6;
+
+    var cache: maxminddb.Cache(maxminddb.any.Value) = .{};
+    defer cache.deinit();
+
+    std.debug.print("Starting benchmark...\n", .{});
+    var timer = try std.time.Timer.start();
+
+    var it = try db.within(
+        allocator,
+        maxminddb.any.Value,
+        network,
+        .{ .cache = &cache },
+    );
+    defer it.deinit();
+
+    var n: usize = 0;
+    while (try it.next()) |_| {
+        n += 1;
+    }
+
+    const elapsed_ns = timer.read();
+    const elapsed_s = @as(f64, @floatFromInt(elapsed_ns)) /
+        @as(f64, @floatFromInt(std.time.ns_per_s));
+
+    const records_per_second = if (elapsed_s > 0)
+        @as(f64, @floatFromInt(n)) / elapsed_s
+    else
+        0.0;
+
+    std.debug.print("\n--- Benchmark Finished ---\n", .{});
+    std.debug.print("Records:            {d}\n", .{n});
+    std.debug.print("Elapsed Time:       {d} s\n", .{elapsed_s});
+    std.debug.print("Records Per Second: {d}\n", .{records_per_second});
+}

build.zig

@@ -32,6 +32,8 @@ pub fn build(b: *std.Build) void {
         .{ .file = "benchmarks/lookup.zig", .name = "benchmark_lookup" },
         .{ .file = "benchmarks/mycity.zig", .name = "benchmark_mycity" },
         .{ .file = "benchmarks/inspect.zig", .name = "benchmark_inspect" },
+        .{ .file = "benchmarks/within.zig", .name = "benchmark_within" },
+        .{ .file = "benchmarks/within_cache.zig", .name = "benchmark_within_cache" },
     };
 
     {

examples/within.zig

@@ -19,9 +19,10 @@ pub fn main() !void {
     var it = try db.within(allocator, maxminddb.geolite2.City, network, .{});
     defer it.deinit();
 
-    // The iterator owns the values; each next() call invalidates the previous item.
     var n: usize = 0;
     while (try it.next()) |item| {
+        defer item.deinit();
+
         const continent = item.value.continent.code;
         const country = item.value.country.iso_code;
         var city: []const u8 = "";

src/maxminddb.zig

@@ -14,7 +14,7 @@ pub const Reader = reader.Reader;
 pub const Result = reader.Result;
 pub const Metadata = reader.Metadata;
 pub const Iterator = reader.Iterator;
-pub const LookupCache = reader.Cache;
+pub const Cache = reader.Cache;
 pub const Options = reader.Options;
 pub const LookupOptions = reader.LookupOptions;
 pub const WithinOptions = reader.WithinOptions;
@@ -887,7 +887,9 @@ test "within returns all networks" {
     defer it.deinit();
 
     var n: usize = 0;
-    while (try it.next()) |_| : (n += 1) {}
+    while (try it.next()) |item| : (n += 1) {
+        item.deinit();
+    }
 
     try expectEqual(242, n);
 }
@@ -908,14 +910,16 @@ test "within yields record when query prefix is narrower than record network" {
     defer it.deinit();
 
     const item = (try it.next()) orelse return error.TestExpectedNotNull;
+    defer item.deinit();
     try expectEqual(17, item.network.prefix_len);
 
     var out: [256]u8 = undefined;
     var w = std.io.Writer.fixed(&out);
     try item.network.format(&w);
     try expectEqualStrings("89.160.0.0/17", out[0..w.end]);
 
-    if (try it.next()) |_| {
+    if (try it.next()) |i| {
+        i.deinit();
         return error.TestExpectedNull;
     }
 }
@@ -933,9 +937,11 @@ test "within yields record when start node is a data pointer" {
     defer it.deinit();
 
     const item = (try it.next()) orelse return error.TestExpectedNotNull;
+    defer item.deinit();
     try expectEqual(0, item.network.prefix_len);
 
-    if (try it.next()) |_| {
+    if (try it.next()) |i| {
+        i.deinit();
         return error.TestExpectedNull;
     }
 }
@@ -973,7 +979,9 @@ test "within skips empty records" {
         defer it.deinit();
 
         var n: usize = 0;
-        while (try it.next()) |_| : (n += 1) {}
+        while (try it.next()) |item| : (n += 1) {
+            item.deinit();
+        }
         try std.testing.expectEqual(571, n);
     }
 
@@ -985,7 +993,9 @@ test "within skips empty records" {
         defer it.deinit();
 
         var n: usize = 0;
-        while (try it.next()) |_| : (n += 1) {}
+        while (try it.next()) |item| : (n += 1) {
+            item.deinit();
+        }
         try std.testing.expectEqual(8, n);
     }
 }