xtra

xtra copied to clipboard

It is hard to know whether Xtra uses bounded or unbounded channels and how to set them up. Searching documentation for "bounded" does not lead to any hints.

It is hard to get to xtra::Actor::create when expecting this things to be in xtra::address or xtra::message_channel. No other mention about bounded vs unbounded seems to be in the documentation.

README example has None for creating actor, yet it is not clear that it means unbounded.

I suggest:

• Mention words "bounded" and "unbounded" explicitly in xtra::Actor::create doccomment. There is "unboudned", but not "bounded", so searching may fail to find it.
• Maybe add some rustdoc searching aliases, so that if user types "bounded" or "unbounded" in search box, he would see create method.
• Mention ability to use both channel types in READE, in the features list.
• Add a comment in README's example about None meaning not "default settings" (like users may expact), but "unbound mailbox".
• Maybe warn about blocking vs unblocking distinction in xtra::Address::send. do_send seems to already carry the warning, but based on do_sends doccomment alone, it may occur that xtra supports only bound channels. It is hard to get from do_send's "If the actor’s mailbox is full, it will block." to Actor::create's message_cap.
• In xtra::message_channel, mention that the word "channel" is used specially in xtra and hint that user may want to search for the word "mailbox" instead.
• Maybe mention the word "channel" in xtra::Actor::create. Like like "... given the cap for the actor’s mailbox (i.e. channel)".

Good point, I will make sure to clarify this ahead of 0.6.0

A fn bounded and fn unbounded as alternatives to fn create could be one way of handling this.

In case https://github.com/Restioson/xtra/pull/133 lands, we can rename the constructor and have Mailbox::bounded and Mailbox::unbounded which should certainly fix this.

Closing as #133 will land soon! :)

Closing as #133 will land soon! :)

I had it linked to the PR already :D