Reuse buffers instead of allocating new ones via a compile-time DSL
nimble install buffalo
- Reuse memory in hot loops: borrow a buffer, write into it, and hand it back when the scope ends. No fresh allocation every time.
- Zero runtime overhead: the DSL is made of macros, templates, and
{.inline.}procs. A borrow becomes a simplelen = 0reset and direct indexed access. - Two buffer styles:
StaticBufferlives on the stack with a fixed capacity.PooledBufferkeeps a growable backing store that grows once, then stays flat. - Scoped borrow API:
withBorrow(pool, buf): ...gives you a short-lived handle.reuse(buf): ...clears an existing buffer for another pass. - Pragma sugar: mark a local variable with
{.buffalo.}insidebuffaloScopeto get stack scratch that is cleared for you, without paying for a full zero-fill on POD static buffers. - Safety checks at compile time: the borrowed name cannot escape the scope (no
return/result, no storing in another variable, noaddr/unsafeAddr, no nested-routine capture). Safe uses stay allowed:buf.len/buf.cap/buf[i], passing views as call arguments, and explicit copy-out withtoSeq/toString. - Works with common data: zero-copy views and bulk helpers for
seq,string, arrays, raw pointers, andstd/memfiles.
Create the pool once, outside the loop. Inside the loop, withBorrow resets it and lets you fill it again without allocating a new backing store.
import buffalo
proc handle(data: openArray[byte]) =
# do something with the borrowed bytes
discard data.len
var pool = initPool(byte, 4096) # allocate once
for chunk in ["alpha", "beta", "gamma"]:
withBorrow(pool, buf):
buf.copyFrom(chunk) # replace contents, reusing the same memory
handle(buf.toOpenArray()) # pass a zero-copy view
# pool can be reused again laterbuffaloScope rewrites marked locals for reuse. For a POD StaticBuffer, it skips the initial zero-fill and injects a clear() instead.
import buffalo
proc buildMessage(): string =
buffaloScope:
var scratch {.buffalo.}: StaticBuffer[byte, 256]
scratch.copyFrom("hello")
scratch.appendMany(", world")
result = scratch.toString() # explicit copy out of the scopereuse is a small helper: it clears the buffer, then runs your block. Handy when you keep one scratch buffer around.
import buffalo
var scratch: StaticBuffer[byte, 128]
scratch.len = 0
for word in ["one", "two", "three"]:
reuse(scratch):
scratch.copyFrom(word)
# work with scratch.toOpenArray() herememView gives you an openArray[byte] over the mapped file, so you can scan it directly. If you want to keep the bytes, copy them into a reusable buffer.
import std/memfiles
import buffalo
var mf = memfiles.open("data.bin", fmRead)
try:
let view = memView(mf) # zero-copy view over the file
# process view...
var buf = initPool(byte, mf.size)
buf.copyFromMemFile(mf) # explicit copy into reusable storage
finally:
mf.close()A borrowed buffer must stay inside its scope. To keep the result, make a copy with toSeq or toString.
import buffalo
proc collect(): seq[byte] =
var pool = initPool(byte, 64)
withBorrow(pool, buf):
buf.appendMany([1'u8, 2, 3])
result = buf.toSeq() # copies the bytes, so they can leave safely- 🐛 Found a bug? Create a new Issue
- 👋 Wanna help? Fork it!
MIT license | Nim Community.