create ~max_size ~compute_size ()
is an empty queue that can hold at most max_size
"bytes" of data, using compute_size
to compute the number of "bytes" in a datum.
Note that you can use max_size
/compute_size
to actually limit the size in byte (i.e., the memory footprint of the structure (in this case, consider using push_overhead
to account for the boilerplate memory), but you can also use max_size
/compute_size
to limit the footprint of the structure for some other resource. E.g., you can spin up tasks in separate processes and limit the number of concurrently running processes.
Also note that the size bound is not inclusive. So with max_size
set to 2
and compute_size
to fun _ -> 1
you can add one (1) element and then the pipe is full. (It is full because adding any other element would take the total size to 2
which is not strictly smaller than the max_size
bound.)
Finally, note that when the pipe is empty, inserting an element will always succeed immediately, even if its size exceed the size bound. For the same reason, inserting an element bigger than the size bound will eventually succeeds, but only once the pipe has been emptied. Once such an element has been inserted, no other element can be pushed until the bigger-than-bound element is popped. This behaviour breaks the invariant guaranteed by the module, but is kept for backwards compatibility. It may be changed in the future, but only after a careful review of the potential impact.