Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8619d384 authored by Michael S. Tsirkin's avatar Michael S. Tsirkin Committed by David S. Miller
Browse files

ptr_ring: clean up documentation 



The only function safe to call without locks
is __ptr_ring_empty. Move documentation about
lockless use there to make sure people do not
try to use __ptr_ring_peek outside locks.

Signed-off-by: default avatarMichael S. Tsirkin <mst@redhat.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 406de755

include/linux/ptr_ring.h

+18 −16
Original line number Diff line number Diff line
@@ -169,21 +169,6 @@ static inline int ptr_ring_produce_bh(struct ptr_ring *r, void *ptr) 
	return ret;

}



/* Note: callers invoking this in a loop must use a compiler barrier,

 * for example cpu_relax(). Callers must take consumer_lock

 * if they dereference the pointer - see e.g. PTR_RING_PEEK_CALL.

 * If ring is never resized, and if the pointer is merely

 * tested, there's no need to take the lock - see e.g.  __ptr_ring_empty.

 * However, if called outside the lock, and if some other CPU

 * consumes ring entries at the same time, the value returned

 * is not guaranteed to be correct.

 * In this case - to avoid incorrectly detecting the ring

 * as empty - the CPU consuming the ring entries is responsible

 * for either consuming all ring entries until the ring is empty,

 * or synchronizing with some other CPU and causing it to

 * execute __ptr_ring_peek and/or consume the ring enteries

 * after the synchronization point.

 */

static inline void *__ptr_ring_peek(struct ptr_ring *r)

{

	if (likely(r->size))
@@ -191,7 +176,24 @@ static inline void *__ptr_ring_peek(struct ptr_ring *r) 
	return NULL;

}



/* See __ptr_ring_peek above for locking rules. */

/*

 * Test ring empty status without taking any locks.

 *

 * NB: This is only safe to call if ring is never resized.

 *

 * However, if some other CPU consumes ring entries at the same time, the value

 * returned is not guaranteed to be correct.

 *

 * In this case - to avoid incorrectly detecting the ring

 * as empty - the CPU consuming the ring entries is responsible

 * for either consuming all ring entries until the ring is empty,

 * or synchronizing with some other CPU and causing it to

 * re-test __ptr_ring_empty and/or consume the ring enteries

 * after the synchronization point.

 *

 * Note: callers invoking this in a loop must use a compiler barrier,

 * for example cpu_relax().

 */

static inline bool __ptr_ring_empty(struct ptr_ring *r)

{

	return !__ptr_ring_peek(r);