Something went wrong. Try again.
zig utility library forked from karlseguin.tngl.sh/zul
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112---layout: site.njktitle: zul.pool---
<h1 id=zul.pool.Growing><a href=#zul.pool.Growing aria-hidden=true>zul.pool.Growing</a></h1><p>A thread-safe object pool which will dynamically grow when empty and revert to the configured size.</p>
<h2 id=example><a href=#example aria-hidden=true>Example</a></h2>{% highlight zig %}// create a pool for our Expensive class.// Our Expensive class takes a special initializing context, here an usize which// we set to 10_000. This is just to pass data from the pool into Expensive.initvar pool = try zul.pool.Growing(Expensive, usize).init(allocator, 10_000, .{.count = 100});defer pool.deinit();
// acquire will either pick an item from the pool// if the pool is empty, it'll create a new one (hence, "Growing")var exp1 = try pool.acquire();defer pool.release(exp1);
...
// pooled object must have 3 functionsconst Expensive = struct { // an init function pub fn init(allocator: Allocator, size: usize) !Expensive { return .{ // ... }; }
// a deinit method pub fn deinit(self: *Expensive) void { // ... }
// a reset method, called when the item is released back to the pool pub fn reset(self: *Expensive) void { // ... }};{% endhighlight %}
<h2><code>fn Growing(comptime T: type, comptime C: type) Growing(T, C)</code></h2><p>The <code>Growing</code> pool is a generic function that takes two parameters. <code>T</code> is the type of object being pool. <code>C</code> is the type of data to pass into <code>T.init</code>. In many cases, <code>C</code> will be <code>void</code>, in which case <code>T.init</code> will not receive the value:</p>
{% highlight zig %}var pool = try zul.pool.Growing(Expensive, void).init(allocator, {}, .{.count = 100});defer pool.deinit();
...
const Expensive = struct { // Because the context was defined as `void`, the `init` function does not // take a 2nd paremeter. pub fn init(allocator: Allocator) !Expensive { return .{ // ... }; }
// ...};{% endhighlight %}
<p><code>T</code> must have an <code>init(allocator: Allocator, ctx: C) !T</code> function. It must also have the following two methods: <code>deinit(self: *T) void</code> and <code>reset(self: *T) void</code>. Because the pool will dynamically create <code>T</code> when empty, <code>deinit</code> will be called when items are released back into a full pool (as well as when <code>pool.deinit</code> is called). <code>reset</code> is called whenever an item is released back into the pool.</p>
<h3 id=Growing.methods><a href=#Growing.methods aria-hidden=true>Methods</a></h3><div> <div class=member> <code class=name id=Growing.init><a href=#Growing.init aria-hidden=true>init(...) !Growing</a></code>{% highlight zig %}fn init( // Allocator is used to create the pool, create the pooled items, and is passed // to the T.init allocator: std.mem.Allocator,
// An arbitrary context to passed to T.init ctx: C
opts: .{ // number of items to keep in the pool .count: usize, }) !Growing(T, C){% endhighlight %} <div class=desc> <p>Creates a <code>pool.Growing</code>.</p> </div> </div> <div class=member> <code class=name id=Growing.deinit><a href=#Growing.deinit aria-hidden=true>deinit(self: *Growing(T, C)) void</a></code> <div class=desc> <p>This is method thread-safe.</p> </div> </div> <div class=member> <code class=name id=Growing.acquire><a href=#Growing.acquire aria-hidden=true>acquire(self: *Growing(T, C)) !*T</a></code> <div class=desc> <p>Returns an <code>*T</code>. When available, <code>*T</code> will be retrieved from the pooled objects. When the pool is empty, a new <code>*T</code> is created.</p> </div> </div> <div class=member> <code class=name id=Growing.release><a href=#Growing.release aria-hidden=true>release(self: *Growing(T, C), t: *T) void</a></code> <div class=desc> <p>Releases <code>*T</code> back into the pool. If the pool is full, <code>t.deinit()</code> is called and then discarded.</p> </div> </div></div>