Skip to content

Commit

Permalink
doc: specify thread safety for each data structure
Browse files Browse the repository at this point in the history
The documentation of "Kernel/Data Structures" incorrectly
states that 'all provided structures are uniformly unsynchronized;
access to them is not threadsafe by default'.
In reality, some of them are threadsafe and some are not.
This might discourage users from using threadsafe data structures
where applicable, or mislead users into adding unnecessary locks.

This proposal addresses the issue by specifying thread safety
for each provided data structure.
My assessment of thread safety is based purely on source code analysis;
hence an expert verification would be appreciated.

(cherry picked from commit 124aae3)

Original-Signed-off-by: Vukan Turkulov <vukant@gmail.com>
GitOrigin-RevId: 124aae3
Cr-Build-Id: 8732568629207591185
Cr-Build-Url: https://cr-buildbucket.appspot.com/build/8732568629207591185
Copybot-Job-Name: zephyr-main-copybot-downstream
Change-Id: I843e03b148cb61a7ac7588495493cb6ecd941984
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/zephyr/+/5982822
Reviewed-by: Ting Shen <phoenixshen@chromium.org>
Commit-Queue: Ting Shen <phoenixshen@chromium.org>
Tested-by: ChromeOS Prod (Robot) <chromeos-ci-prod@chromeos-bot.iam.gserviceaccount.com>
  • Loading branch information
Moon-Raven authored and Chromeos LUCI committed Oct 31, 2024
1 parent 5b3ad5a commit 01549a8
Showing 1 changed file with 4 additions and 2 deletions.
6 changes: 4 additions & 2 deletions doc/kernel/data_structures/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,12 @@ behind this design is to allow the collections to be used in contexts
where dynamic allocation is disallowed (i.e. there is no need to
allocate node objects because the memory is provided by the user).

Note also that these libraries are uniformly unsynchronized; access to
Note also that these libraries are generally unsynchronized; access to
them is not threadsafe by default. These are data structures, not
synchronization primitives. The expectation is that any locking
needed will be provided by the user.
needed will be provided by the user. Some of the provided data
structures are thread safe in specific usage scenarios (see
:ref:`spsc_lockfree` and :ref:`mpsc_lockfree`).

.. toctree::
:maxdepth: 1
Expand Down

0 comments on commit 01549a8

Please sign in to comment.