core/cib: Add a prominent warning about thread safety

maribu · mguetschow · maribu · commit dcd3ee74ae5e · 2025-04-14T14:29:56.000+02:00
Users of CIB may easily be mislead to believing that it is generally
thread safe, or at least thread safe as long as there is a single
consumer and producer. Neither is the case, which now is clearly
communicated in the API doc.

Co-authored-by: mguetschow &lt;mikolai.guetschow@tu-dresden.de&gt;
diff --git a/core/lib/include/cib.h b/core/lib/include/cib.h
@@ -17,6 +17,17 @@
  *              and combined with an memory array forms a circular buffer.
  *
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @warning     This API is NOT thread-safe.
+ *
+ * @note        It may appear that the functions would be thread safe if the
+ *              management data structure is only ever accessed by a single
+ *              consumer and a singler producer on platforms where loads and
+ *              stores to `unsigned int` is atomic. But even this is not the
+ *              case, as this would require careful use of memory barriers to
+ *              ensure correct order of memory accesses. So: Just make sure
+ *              to use either a mutex or to disable interrupts to ensure
+ *              exclusive access as indicated in the API doc.
  */
 
 #ifndef CIB_H
@@ -84,6 +95,9 @@ static inline unsigned int cib_size(const cib_t *cib)
  * @param[in] cib       the cib_t to check.
  *                      Must not be NULL.
  * @return How often cib_get() can be called before @p cib is empty.
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline unsigned int cib_avail(const cib_t *cib)
 {
@@ -96,6 +110,9 @@ static inline unsigned int cib_avail(const cib_t *cib)
  * @param[in] cib       the cib_t to check.
  *                      Must not be NULL.
  * @return      1 if cib_put() would return "-1", 0 otherwise
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline unsigned int cib_full(const cib_t *cib)
 {
@@ -109,6 +126,9 @@ static inline unsigned int cib_full(const cib_t *cib)
  *                      Must not be NULL.
  * @return index of next item
  * @retval -1 if the buffer is empty
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_get(cib_t *__restrict cib)
 {
@@ -134,6 +154,10 @@ static inline int cib_get(cib_t *__restrict cib)
  *
  * @return index of item
  * @retval -1 if no item at @p offset exists in the buffer
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t` and must not release that exclusive
+ *          access between the call to @ref cib_avail and this function.)
  */
 static inline int cib_peek_at_unsafe(const cib_t *__restrict cib, unsigned offset)
 {
@@ -152,6 +176,9 @@ static inline int cib_peek_at_unsafe(const cib_t *__restrict cib, unsigned offse
  *
  * @return index of item
  * @retval -1 if no item at @p offset exists in the buffer
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_peek_at(const cib_t *__restrict cib, unsigned offset)
 {
@@ -171,6 +198,10 @@ static inline int cib_peek_at(const cib_t *__restrict cib, unsigned offset)
  *                      Must not be NULL.
  * @return index of next item
  * @retval -1 if the buffer is empty
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t` and must not release that exclusive
+ *          access between the call to @ref cib_avail and this function.)
  */
 static inline int cib_peek_unsafe(const cib_t *__restrict cib)
 {
@@ -184,6 +215,9 @@ static inline int cib_peek_unsafe(const cib_t *__restrict cib)
  *                      Must not be NULL.
  * @return index of next item
  * @retval -1 if the buffer is empty
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_peek(const cib_t *__restrict cib)
 {
@@ -198,6 +232,9 @@ static inline int cib_peek(const cib_t *__restrict cib)
  * @param[in,out] cib   corresponding *cib* to buffer.
  *                      Must not be NULL.
  * @return index of next item
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_get_unsafe(cib_t *cib)
 {
@@ -211,6 +248,9 @@ static inline int cib_get_unsafe(cib_t *cib)
  *                      Must not be NULL.
  * @return index of item to put to
  * @retval -1 if the buffer is full
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_put(cib_t *__restrict cib)
 {
@@ -232,6 +272,9 @@ static inline int cib_put(cib_t *__restrict cib)
  * @param[in,out] cib   corresponding *cib* to buffer.
  *                      Must not be NULL.
  * @return index of item to put to
+ *
+ * @warning This function is not thread safe. (The caller needs to ensure
+ *          exclusive access to the `cib_t`.)
  */
 static inline int cib_put_unsafe(cib_t *cib)
 {
