queue::push incoherent documentation

[viboes]

The documentation of queue::push states in the postcondition that the object is pushed if the queue if internal node can be allocated, but this in contradiction with Note that states that a new node could be allocated from the OS.

I suggest to add a Effects clause to all the documentation to states clearly the effects of each function, as it done for the C++ standard and a lot of Boost libraries.

bool push(T const & t);

Pushes object t to the queue.

Note

Thread-safe. If internal memory pool is exhausted and the memory pool is not fixed-sized, a new node will be allocated from the OS. This may not be lock-free.

Postconditions:

object will be pushed to the queue, if internal node can be allocated

Returns:

true, if the push operation is successful.

[timblechmann]

it is not really a contradiction, because the queue has two allocation schemes:

• an internal memory pool
• the OS

both allocation schemes may fail. changing the postconditon' clause to effects' might be reasonable, though ...

[viboes]

Replying to timblechmann:

it is not really a contradiction, because the queue has two allocation schemes:

• an internal memory pool
• the OS

both allocation schemes may fail. changing the postconditon' clause to effects' might be reasonable, though ...

The problem is when internal memory pool fail but OS gives you memory. In this case the current postcondition is false as the object will be pushed to the queue even if the internal pool fails.

[anonymous]

The problem is when internal memory pool fail but OS gives you memory. In this case the current postcondition is false as the object will be pushed to the queue even if the internal pool fails.

not really, but maybe 'internal node' is ambiguous: it is 'internal' as in 'internally used' node, not 'allocated from the internal freelist' ... hm