[rtems-docs commit] c-users: Add rtems_*mutex_try_lock

[Christian Mauderer]

Module:    rtems-docs
Branch:    master
Commit:    b05cecc7dac13fcbe5fd879c0c0dbd3cba57dff7
Changeset: http://git.rtems.org/rtems-docs/commit/?id=b05cecc7dac13fcbe5fd879c0c0dbd3cba57dff7

Author:    Christian Mauderer <christian.mauderer at embedded-brains.de>
Date:      Wed May 26 11:32:55 2021 +0200

c-users: Add rtems_*mutex_try_lock

Closes #4440.

---

 c-user/self_contained_objects.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/c-user/self_contained_objects.rst b/c-user/self_contained_objects.rst
index 0be1423..10d2b91 100644
--- a/c-user/self_contained_objects.rst
+++ b/c-user/self_contained_objects.rst
@@ -132,6 +132,10 @@ copies of the object in calls to
 
 * :c:func:`rtems_recursive_mutex_lock`,
 
+* :c:func:`rtems_mutex_try_lock`,
+
+* :c:func:`rtems_recursive_mutex_try_lock`,
+
 * :c:func:`rtems_mutex_unlock`,
 
 * :c:func:`rtems_recursive_mutex_unlock`,
@@ -262,6 +266,37 @@ NOTES:
 
     \clearpage
 
+Try to lock the mutex
+---------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_mutex_try_lock(
+          rtems_mutex *mutex
+        );
+
+        int rtems_recursive_mutex_try_lock(
+          rtems_recursive_mutex *mutex
+        );
+
+DESCRIPTION:
+    Tries to lock the ``mutex``. In case the mutex is not locked, it will be
+    locked and the function returns with a return value of ``0``. If the mutex
+    is already locked, the function will return with a value of ``EBUSY``.
+
+NOTES:
+    This function must be called from thread context with interrupts enabled.
+
+    For recursively locking a mutex, please also see the notes for
+    :c:func:`rtems_mutex_lock` and :c:func:`rtems_recursive_mutex_lock`.
+
+    Each mutex lock operation must have a corresponding unlock operation.
+
+.. raw:: latex
+
+    \clearpage
+
 Unlock the mutex
 ----------------