Separate methods to use cache, rename within to scan

Author: marselester

README.md

@@ -54,13 +54,37 @@ var db = try maxminddb.Reader.mmap(allocator, db_path, .{ .ipv4_index_first_n_bi
 defer db.close();
 ```
 
-Use `ArenaAllocator` for best performance, see [benchmarks](./benchmarks/).
+Each `lookup` result owns an arena with all decoded allocations.
+Call `deinit()` to free it or use `ArenaAllocator` with `reset()`,
+see [benchmarks](./benchmarks/lookup.zig).
+
+```zig
+if (try db.lookup(maxminddb.geolite2.City, allocator, ip, .{})) |result| {
+    defer result.deinit();
+    std.debug.print("{f} {s}\n", .{ result.network, result.value.city.names.?.get("en").? });
+}
+
+var arena = std.heap.ArenaAllocator.init(allocator);
+defer arena.deinit();
+
+const arena_allocator = arena.allocator();
+for (ips) |ip| {
+    if (try db.lookup(maxminddb.geolite2.City, arena_allocator, ip, .{})) |result| {
+        std.debug.print("{f} {s}\n", .{ result.network, result.value.city.names.?.get("en").? });
+    }
+
+    _ = arena.reset(.retain_capacity);
+}
+```
 
 If you don't need all the fields, use `.only` to decode only the top-level fields you want.
 
 ```zig
 const fields = &.{ "city", "country" };
-const city = try db.lookup(allocator, maxminddb.geolite2.City, ip, .{ .only = fields });
+if (try db.lookup(maxminddb.geolite2.City, allocator, ip, .{ .only = fields })) |result| {
+    defer result.deinit();
+    std.debug.print("{f} {s}\n", .{ result.network, result.value.city.names.?.get("en").? });
+}
 ```
 
 Alternatively, define your own struct with only the fields you need.
@@ -74,36 +98,42 @@ const MyCity = struct {
     } = .{},
 };
 
-const city = try db.lookup(allocator, MyCity, ip, .{});
+if (try db.lookup(MyCity, allocator, ip, .{})) |result| {
+    defer result.deinit();
+    std.debug.print("{s}\n", .{result.value.city.names.en});
+}
 ```
 
 Use `any.Value` to decode any record without knowing the schema.
 
 ```zig
-const result = try db.lookup(allocator, maxminddb.any.Value, ip, .{ .only = fields });
-if (result) |r| {
+if (try db.lookup(maxminddb.any.Value, allocator, ip, .{ .only = fields })) |result| {
+    defer result.deinit();
     // Formats as compact JSON.
-    std.debug.print("{f}\n", .{r.value});
+    std.debug.print("{f}\n", .{result.value});
 }
 ```
 
-Use a `Cache` to skip decoding when different IPs resolve to the same record.
+Use `lookupWithCache` to skip decoding when different IPs resolve to the same record.
+The cache owns decoded memory, so results don't need to be individually freed.
 
 ```zig
-var cache: maxminddb.Cache(maxminddb.geolite2.City) = .{};
+var cache = try maxminddb.Cache(maxminddb.geolite2.City).init(allocator, .{});
 defer cache.deinit();
 
-const city = try db.lookup(allocator, maxminddb.geolite2.City, ip, .{ .cache = &cache });
+if (try db.lookupWithCache(maxminddb.geolite2.City, &cache, ip, .{})) |result| {
+    std.debug.print("{f} {s}\n", .{ result.network, result.value.city.names.?.get("en").? });
+}
 ```
 
 Here are reference results on Apple M2 Pro (1M random IPv4 lookups against GeoLite2-City
 with `ipv4_index_first_n_bits = 16`):
 
-| Type             | Default    | `.only`    | `Cache`    |
-|---               |---         |---         |---         |
-| `geolite2.City`  | ~1,284,000 | ~1,348,000 | ~1,474,000 |
-| `MyCity`         | ~1,383,000 |            |            |
-| `any.Value`      | ~1,254,000 | ~1,349,000 |            |
+| Type            | Default    | `.only`    | `Cache`    |
+|---              |---         |---         |---         |
+| `geolite2.City` | ~1,420,000 | ~1,348,000 | ~1,565,000 |
+| `MyCity`        | ~1,383,000 |            |            |
+| `any.Value`     | ~1,254,000 | ~1,349,000 |            |
 
 <details>
 
@@ -237,42 +267,45 @@ Lookups Per Second (avg):1315986.2950186788
 
 </details>
 
-Use `within()` to iterate over all networks in the database.
-A `Cache` avoids re-decoding networks that share the same record.
+Use `scan` to iterate over all networks in the database.
 
 ```zig
-var cache: maxminddb.Cache(maxminddb.any.Value) = .{};
+var it = try db.scan(maxminddb.any.Value, allocator, maxminddb.Network.all_ipv6, .{});
+
+while (try it.next()) |item| {
+    defer item.deinit();
+    std.debug.print("{f} {f}\n", .{ item.network, item.value });
+}
+```
+
+Use `scanWithCache` to avoid re-decoding networks that share the same record.
+The cache owns decoded memory, so results don't need to be individually freed.
+
+```zig
+var cache = try maxminddb.Cache(maxminddb.any.Value).init(allocator, .{});
 defer cache.deinit();
 
-var it = try db.within(
-    allocator,
-    maxminddb.any.Value,
-    maxminddb.Network.all_ipv6,
-    .{ .cache = &cache },
-);
-defer it.deinit();
+var it = try db.scanWithCache(maxminddb.any.Value, &cache, maxminddb.Network.all_ipv6, .{});
 
 while (try it.next()) |item| {
-    std.debug.print("{f} {f}\n", .{item.network, item.value});
+    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`):
 
-| Mode      | Records/sec |
-|---        |---          |
-| Default   | ~1,235,000  |
-| `Cache`   | ~2,900,000  |
+| Mode    | Records/sec |
+|---      |---          |
+| Default | ~1,295,000  |
+| `Cache` | ~2,930,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 \
+    zig build benchmark_scan -Doptimize=ReleaseFast -- GeoLite2-City.mmdb \
       2>&1 | grep 'Records Per Second'
   done
 
@@ -296,7 +329,7 @@ Records Per Second: 1246311.587919839
 
 ```sh
 $ for i in $(seq 1 10); do
-    zig build benchmark_within_cache -Doptimize=ReleaseFast -- GeoLite2-City.mmdb \
+    zig build benchmark_scan_cache -Doptimize=ReleaseFast -- GeoLite2-City.mmdb \
       2>&1 | grep 'Records Per Second'
   done
 

benchmarks/inspect.zig

@@ -59,8 +59,8 @@ pub fn main() !void {
         const ip = std.net.Address.initIp4(ip_bytes, 0);
 
         const result = db.lookup(
-            arena_allocator,
             maxminddb.any.Value,
+            arena_allocator,
             ip,
             .{ .only = fields },
         ) catch |err| {

benchmarks/lookup.zig

@@ -59,8 +59,8 @@ pub fn main() !void {
         const ip = std.net.Address.initIp4(ip_bytes, 0);
 
         const result = db.lookup(
-            arena_allocator,
             maxminddb.geolite2.City,
+            arena_allocator,
             ip,
             .{ .only = fields },
         ) catch |err| {

benchmarks/lookup_cache.zig

@@ -43,13 +43,9 @@ pub fn main() !void {
         db.metadata.database_type,
     });
 
-    var cache: maxminddb.Cache(maxminddb.geolite2.City) = .{};
+    var cache = try maxminddb.Cache(maxminddb.geolite2.City).init(allocator, .{});
     defer cache.deinit();
 
-    var arena = std.heap.ArenaAllocator.init(allocator);
-    defer arena.deinit();
-    const arena_allocator = arena.allocator();
-
     std.debug.print("Starting benchmark...\n", .{});
     var timer = try std.time.Timer.start();
     var not_found_count: u64 = 0;
@@ -60,11 +56,11 @@ pub fn main() !void {
         std.crypto.random.bytes(&ip_bytes);
         const ip = std.net.Address.initIp4(ip_bytes, 0);
 
-        const result = db.lookup(
-            arena_allocator,
+        const result = db.lookupWithCache(
             maxminddb.geolite2.City,
+            &cache,
             ip,
-            .{ .only = fields, .cache = &cache },
+            .{ .only = fields },
         ) catch |err| {
             std.debug.print("! Lookup error for IP {any}: {any}\n", .{ ip, err });
             lookup_errors += 1;
@@ -74,8 +70,6 @@ pub fn main() !void {
             not_found_count += 1;
             continue;
         }
-
-        _ = arena.reset(.retain_capacity);
     }
 
     const elapsed_ns = timer.read();

benchmarks/mycity.zig

@@ -53,8 +53,8 @@ pub fn main() !void {
         const ip = std.net.Address.initIp4(ip_bytes, 0);
 
         const result = db.lookup(
-            arena_allocator,
             MyCity,
+            arena_allocator,
             ip,
             .{},
         ) catch |err| {

benchmarks/within.zig benchmarks/scan.zigbenchmarks/within.zig renamed to benchmarks/scan.zig

@@ -34,8 +34,7 @@ pub fn main() !void {
     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 it = try db.scan(maxminddb.any.Value, allocator, network, .{});
 
     var n: usize = 0;
     while (try it.next()) |item| {

benchmarks/within_cache.zig benchmarks/scan_cache.zigbenchmarks/within_cache.zig renamed to benchmarks/scan_cache.zig

@@ -31,19 +31,18 @@ pub fn main() !void {
     else
         maxminddb.Network.all_ipv6;
 
-    var cache: maxminddb.Cache(maxminddb.any.Value) = .{};
+    var cache = try maxminddb.Cache(maxminddb.any.Value).init(allocator, .{});
     defer cache.deinit();
 
     std.debug.print("Starting benchmark...\n", .{});
     var timer = try std.time.Timer.start();
 
-    var it = try db.within(
-        allocator,
+    var it = try db.scanWithCache(
         maxminddb.any.Value,
+        &cache,
         network,
-        .{ .cache = &cache },
+        .{},
     );
-    defer it.deinit();
 
     var n: usize = 0;
     while (try it.next()) |_| {

build.zig

@@ -27,14 +27,14 @@ pub fn build(b: *std.Build) void {
         name: []const u8,
     }{
         .{ .file = "examples/lookup.zig", .name = "example_lookup" },
-        .{ .file = "examples/within.zig", .name = "example_within" },
         .{ .file = "examples/inspect.zig", .name = "example_inspect" },
+        .{ .file = "examples/scan.zig", .name = "example_scan" },
         .{ .file = "benchmarks/lookup.zig", .name = "benchmark_lookup" },
         .{ .file = "benchmarks/lookup_cache.zig", .name = "benchmark_lookup_cache" },
         .{ .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" },
+        .{ .file = "benchmarks/scan.zig", .name = "benchmark_scan" },
+        .{ .file = "benchmarks/scan_cache.zig", .name = "benchmark_scan_cache" },
     };
 
     {

examples/inspect.zig

@@ -15,8 +15,8 @@ pub fn main() !void {
     defer db.close();
 
     const result = try db.lookup(
-        allocator,
         maxminddb.any.Value,
+        allocator,
         try std.net.Address.parseIp(ip, 0),
         .{},
     ) orelse {

examples/lookup.zig

@@ -14,7 +14,7 @@ pub fn main() !void {
     // Note, for better performance use arena allocator and reset it after calling lookup().
     // You won't need to call city.deinit() in that case.
     const ip = try std.net.Address.parseIp("89.160.20.128", 0);
-    const city = try db.lookup(allocator, maxminddb.geoip2.City, ip, .{}) orelse return;
+    const city = try db.lookup(maxminddb.geoip2.City, allocator, ip, .{}) orelse return;
     defer city.deinit();
 
     for (city.value.country.names.?.entries) |e| {