From 95cc663e4312e2837ef726a5ac582e2e1cce55d2 Mon Sep 17 00:00:00 2001 From: Nat Goodspeed Date: Sat, 15 Aug 2015 11:20:19 -0400 Subject: [PATCH] Correctly describe bounded_channel's behavior with lwm items. I originally assumed that a blocked bounded_channel::push() would only unblock once the number of items in the channel dropped _below_ lwm, and described it that way. But in fact the push unblocks as soon as the number of items in the channel drops as low as lwm. Update documentation accordingly. --- doc/channel.qbk | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/channel.qbk b/doc/channel.qbk index 8122f42e..4e393f0a 100644 --- a/doc/channel.qbk +++ b/doc/channel.qbk @@ -266,16 +266,15 @@ time as (system time + `timeout_duration`). bounded_channel( std::size_t hwm, std::size_t lwm); [variablelist -[[Preconditions:] [`hwm >= lwm`]] +[[Preconditions:] [`hwm > lwm`]] [[Effects:] [Constructs an object of class `bounded_channel`. The constructor with two arguments constructs an object of class `bounded_channel` with a high-watermark of `hwm` and a low-watermark of `lwm` items. The constructor -with one argument effectively sets both `hwm` and `lwm` to the same value -`wm`.]] -[[Throws:] [`invalid_argument` if `lwm > hwm`.]] +with one argument is effectively the same as `bounded_channel(wm, (wm-1))`.]] +[[Throws:] [`invalid_argument` if `lwm >= hwm`.]] [[Notes:] [Once the number of values in the channel reaches `hwm`, any call to `push()`, `push_wait_for()` or `push_wait_until()` will block until the number -of values in the channel has dropped below `lwm`. That is, if `lwm < hwm`, the +of values in the channel is at most `lwm`. That is, if `lwm < (hwm-1)`, the channel can be in a state in which `push()`, `push_wait_for()` or `push_wait_until()` calls will block (channel is full) even though the number of values in the channel is less than `hwm`.]] @@ -303,7 +302,7 @@ in the channel is less than `hwm`.]] [template bounded_channel_push_effects[or] [xchannel_push_effects If channel is not full, enqueues] Otherwise the calling fiber is suspended until -the number of values in the channel drops below `lwm` (return value +the number of values in the channel drops to `lwm` (return value `success`)[or] the channel is `close()`d (return value `closed`)] [member_heading bounded_channel..push] @@ -361,7 +360,7 @@ time_point (return value `timeout`).]] ] [template bounded_pop_unblocking[] Once the number of items remaining in the -channel drops below `lwm`, any fibers blocked on `push()`, `push_wait_for()` +channel drops to `lwm`, any fibers blocked on `push()`, `push_wait_for()` or `push_wait_until()` may resume.] [xchannel_pop bounded_channel... [bounded_pop_unblocking]]