Document allocation behaviour of mpsc and other channels

[barafael]

Say I have a program utilizing tokio and many mpsc channels, and I'm expecting it to take quite some load, occasionally. How do I estimate the memory usage of the channels and the general allocation behaviour of the program?

I can measure and I will see that bounded mpsc allocates chunks at a time, and that it does not seem to deallocate them after allocating them once.

Questions remain: Does the chunk size depend on the number of elements already in the channel in some way? Does the channel NEVER deallocate, or deallocate at some later point in time? How much overhead is there, per channel element? Are there advantages to using channel sizes that are power of 2s? Is it OK to make an mpsc channel with 10 million elements?

Solution: Documentation?

It would be useful in that case to document these behaviours.

It would be understandable if those behaviours are expected to change and thus users should abstain from making any assumptions about them. That would also perhaps be worth a remark.

Additional context
mpsc would be the most useful for me, and I see in general that the question usually comes up with mpsc because of its wide use, but it might also be interesting for broadcast.

[Darksonn]

I would be happy to see things documented, but we may change it in the future.

To give a short answer to your question, the mpsc channel allocates chunks with space for 32 messages. The chunks are in a linked list. When the last message is removed from a chunk, then it is freed. Though there is some logic to reuse chunks instead of freeing them, so if the chunk that messages are currently being added to has no next chunk, it will move the empty chunk there instead of freeing it.

The capacity of the channel has no effect on this logic. The bounded channel is just an unbounded one plus a semaphore. This is so that extremely large capacities don't immediately consume all of your memory.

The channel has one byte of overhead per message, as each 32-element chunk uses 4 pointer-sized fields for bookkeeping.

[barafael]

Thanks very much for your detailed response and explanation. Do you think this should be documented, or rather stay implicit, not to be relied upon?

[Darksonn]

I would be happy to see things documented. But it will be subject to changes in future releases.

[barafael]

I'll do a PR with the info you gave.