pbwire 0.1.15 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad30ac9faae27fbdc594301b069fc94f73c2a31f361ee166af48461e3b6bad95
-  data.tar.gz: 47e7270855389b63c84958a310dbfa070165fcd6129da7cb8ef7174250e05955
+  metadata.gz: 7dd94f55ce589d8950dccaa9be49b72ccaeaf41f2e8e8d0cb618e277b9f390a9
+  data.tar.gz: e2ec6aad9f8f6388052549fa6a36dc800d20a92a374ae11c6c88c47fb0ef84af
 SHA512:
-  metadata.gz: 8778428e622e26ce0b9296f397df25bddac8b49e343739e19f342f3b780393607622bbe01cf66a6ec3edc1e4219e7806a79ffa50551740e4bdb4d821e6a648bf
-  data.tar.gz: 95926579ae088274eae6ff6eff71f2dd78367e72b64dd077c81cd0e0153430c7760a0c5cdcac64e882aa340f54897cf5b8b2eba4471371797ebcb5e04d62432a
+  metadata.gz: d8271cb299cd323b746b9030f2589eb2e9458d8ced67e760d956b25db915e488dd83ced3b332635206b8f0d3ac4766415c6ca05a512dace2cba657a4c9a649bb
+  data.tar.gz: f8777686778ccd31fa9f5cbff856f7770fb9f67d44935171f8b4c329c5fdceb94975ce2f8e9b373f77f52e938123292c7915afcd367c47ee8a7ae7ebec9cca93

data/README.md

@@ -159,6 +159,30 @@ String do not change the message. A borrowed sub-message returned by `get` is
 owned by its parent: it keeps the parent alive and refuses to be used after the
 parent is closed.
 
+### Contexts and pools
+
+`Pbwire::Context` is the C `pbw_ctx` workspace (an arena plus a reusable encode
+buffer), and `Pbwire::Pool` is a bounded freelist of them, for a server that
+decodes in a tight loop:
+
+```ruby
+ctx = Pbwire::Context.new
+ctx.decode(schema, "pkg.Msg", wire)   # read-only view, dies with the next reset
+ctx.encode(msg)                       # into the context's buffer
+ctx.used                              # bytes held now
+ctx.retain_cap = 64 * 1024            # resident ceiling (1 MiB default)
+ctx.reset                             # frees everything since the last reset
+
+pool = Pbwire::Pool.new(max_idle: 8, retain_cap: 64 * 1024)
+ctx = pool.acquire
+# ... use ctx ...
+pool.release(ctx)                     # already reset for the next acquire
+```
+
+A message decoded through a context borrows it: after `reset` (or a pool
+`release`) it raises `"context was reset"` instead of reading freed arena
+memory.
+
 ## Repeated fields, maps, groups
 
 Repeated scalars (packed or unpacked on the wire), repeated strings/bytes and