Re: [boost] [rfc] lockfree API/naming suggestions

Subject: Re: [boost] [rfc] lockfree API/naming suggestions
From: Tim Blechmann (tim_at_[hidden])
Date: 2011-11-29 12:39:18

hi vincente & dave,

> > personally i'd be in favor of `ringbuffer' (because i have been using
> > this name for years) or `spsc_queue' (because it makes clear that it
> > doesn't support multiple produces/consumers). but i'd be curious, what
> > other people
> > suggest.
> 
> I think that the type must contains whether it is safe to produce/consume
> from multiple threads. I will use the prefixes: spsc_, spmc_, mpsc_ and
> mpmc_.
> 
> bounded and ring mean different things for me. A bounded queue will block
> when there is no more free space. A ring will override the first element of
> the queue when there is no more space.

i'll try to avoid the term `bounded' and `ring' then, as they seem to have 
different conotations. 
spsc_queue and queue should be the best names then.

vincente:
> however this would imply 3 flavors of `push'
> * push, which may block during memory allocation
> * push_unsafe, which is not thread-safe (but faster)
> * push_nonblocking, which is guaranteed not to hit the memory allocator.
> 
> so i am not sure, whether this introduces too much complexity into the API.
> 
> 
> IMO, the push should corresponds to the expected behavior. As these queues
> are in a lockfree library, I would expect that the push is thread safe. I
> agree with Dave that try_ is a better name for a non blocking operation.
> 
> I don't know in which cases the application can be sure that there is no
> thread safe issues, but  in any case, the interface should be enough ugly to
> make it more difficult to use, as it is unsafe. thread_unsafe_push seems
> quite ugly, isn't it? ;-)

dave:
> If it were me, I wouldn't label anything "unsafe," since presumably even
> the push you're calling unsafe is as threadsafe as int, and it seems
> like the right prefix for the nonblocking one is "try_".  I might use
> ("push", "atomic_push," "try_push") or if the use of the single-threaded
> version is rare enough, ("single_thread_push"/"serial_push", "push",
> "try_push").

"atomic" does have some a different meaning then what is implemented (afaict, 
`linearizable' would be the correct term). 

i'd like to avoid the name "try_", because all push operations may actually 
fail. "push" and "push_unsafe" can fail if ringbuffer (aka spsc_queue) space 
is exhausted or memory allocation fails (queue/stack). "push_nonblocking" may 
fail, if the internal memory pool is exhausted.

"single_thread_push" might cause some misunderstanding, as people may think 
that it is about a `single producer', not about a `single-threaded use'. so it 
is really a "thread_unsafe_push", as incorrect use may corrupt the internal 
data structure.

so maybe "thread_unsafe_push", "nonblocking_push" and "push"?

thanks, tim