Tutorial · Chapter 11 of 23

Keep independent records in a pool

Store two survey notes, release one, and reuse its space while the other stays live.

Jump to a section

Match the allocator to the lifetime

The scratch record from the previous chapter expired after one print. A list of survey notes has a different lifetime. Each note stays live until you have read or replaced it, even when a different note can be discarded.

What you needStorageWhen the bytes can be reused
Several temporary buffers for one taskNear arena in C64 RAMAfter the entire task, with reset.
Independent notes of bounded sizeFixed-block pool in C64 RAMAfter each note, with free.
A table too large for C64 RAMFar arena in REUWhen its handles are out of use, with reset.

Reserve eight bytes at $9200 and set the block size to four. That gives two blocks. A two-byte note uses one block. A five-byte request fails even in an empty pool because it cannot fit in a single block.

Encode a record and reuse only its block

A pool allocation returns a byte pointer, like a near arena allocation. Pass a typed Note to the encoder and use its field offsets to write the record. The pointer is your access to that allocation. Free it only after the last read, and keep the second note live while replacing the first.

survey-pool.zp64
const c64 = @import("c64");

const Note = struct { sector: u8, flags: u8 };

memory {
    region notes_ram: c64 at 0x9200 size 8;
    pool notes in notes_ram block 4;
}

fn writeNote(bytes: [*]u8, note: Note) void {
    bytes[@offsetOf(Note, "sector")] = note.sector;
    bytes[@offsetOf(Note, "flags")] = note.flags;
}

fn showNote(bytes: [*]u8) void {
    const sector = bytes[@offsetOf(Note, "sector")];
    const flags = bytes[@offsetOf(Note, "flags")];
    c64.console.print("SECTOR {x} FLAGS {x}\n", .{ sector, flags });
}

fn run() bool {
    if (notes.allocBytes(@sizeOf(Note))) |first| {
        if (notes.allocBytes(@sizeOf(Note))) |second| {
            writeNote(first, Note{ .sector = 1, .flags = 4 });
            writeNote(second, Note{ .sector = 2, .flags = 8 });
            const extra = notes.allocBytes(@sizeOf(Note));
            if (extra) |spare| {
                notes.free(spare);
            } else {
                c64.console.print("NOTES FULL\n", .{});
            }
            showNote(first);
            notes.free(first);
            if (notes.allocBytes(@sizeOf(Note))) |next| {
                writeNote(next, Note{ .sector = 3, .flags = 2 });
                showNote(second);
                showNote(next);
                notes.free(next);
            }
            notes.free(second);
            return true;
        }
        notes.free(first);
    }
    return false;
}

export fn main() void {
    c64.console.clear();
    if (run() == false) {
        c64.console.print("NEED TWO NOTE BLOCKS\n", .{});
    }
}

Open the complete source

Expect NOTES FULL, then SECTOR 01 FLAGS 04, SECTOR 02 FLAGS 08, and SECTOR 03 FLAGS 02. The second note remains readable after the first block is freed and reused.

Predict what changes when you add a block

Change the region from eight to twelve bytes while keeping four-byte blocks. The third allocation can succeed, so NOTES FULL disappears. The successful branch returns the spare block, and the three notes still print in the same order.

Restore the eight-byte region for the original result. Use reset only when every pointer from the pool can expire together. For a richer actor record and a guide to choosing block size, see Arenas, pools, and records.