docs +

facil-io · Oct 25, 2024 · 0d24d00 · 0d24d00
1 parent 7ff7bf7
commit 0d24d00
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 40 deletions.
diff --git a/fio-stl.h b/fio-stl.h
@@ -755,6 +755,9 @@ Spin-Locks
 #define FIO_LOCK_SUBLOCK(sub) ((uint8_t)(1U) << ((sub)&7))
 typedef volatile unsigned char fio_lock_i;
 
+#ifndef FIO___LOCK_RESCHDULE_EVERY_LOG
+#define FIO___LOCK_RESCHDULE_EVERY_LOG 8
+#endif
 /**
  * Tries to lock a group of sublocks.
  *
@@ -790,7 +793,7 @@ FIO_IFUNC uint8_t fio_trylock_group(fio_lock_i *lock, uint8_t group) {
 FIO_IFUNC void fio_lock_group(fio_lock_i *lock, uint8_t group) {
   size_t i = 0;
   while (fio_trylock_group(lock, group)) {
-    if ((i++ & 64)) {
+    if ((i++ & (1U << FIO___LOCK_RESCHDULE_EVERY_LOG))) {
       i = 0;
       FIO_THREAD_RESCHEDULE();
     }

diff --git a/fio-stl.md b/fio-stl.md
@@ -1427,11 +1427,9 @@ A spinlock type based on a volatile unsigned char.
 
 **Note**: the spinlock contains one main / default lock (`sub == 0`) and 7 sub-locks (`sub >= 1 && sub <= 7`), which could be managed:
 
-- Separately: using the `fio_lock_sublock`, `fio_trylock_sublock` and `fio_unlock_sublock` functions.
-- Jointly: using the `fio_trylock_group`, `fio_lock_group` and `fio_unlock_group` functions.
+- Separately / Jointly: using the `fio_trylock_group`, `fio_lock_group` and `fio_unlock_group` functions.
 - Collectively: using the `fio_trylock_full`, `fio_lock_full` and `fio_unlock_full` functions.
 
-
 #### `fio_lock(fio_lock_i *)`
 
 Busy waits for the default lock (sub-lock `0`) to become available.
@@ -1448,22 +1446,6 @@ Unlocks the default lock (sub-lock `0`), no matter which thread owns the lock.
 
 Returns 1 if the (main) lock is engaged. Otherwise returns 0.
 
-#### `fio_lock_sublock(fio_lock_i *, uint8_t sub)`
-
-Busy waits for a sub-lock to become available.
-
-#### `fio_trylock_sublock(fio_lock_i *, uint8_t sub)`
-
-Attempts to acquire the sub-lock. Returns 0 on success and 1 on failure.
-
-#### `fio_unlock_sublock(fio_lock_i *, uint8_t sub)`
-
-Unlocks the sub-lock, no matter which thread owns the lock.
-
-#### `fio_is_sublocked(fio_lock_i *, uint8_t sub)`
-
-Returns 1 if the specified sub-lock is engaged. Otherwise returns 0.
-
 #### `uint8_t fio_trylock_group(fio_lock_i *lock, const uint8_t group)`
 
 Tries to lock a group of sub-locks.
@@ -1492,6 +1474,10 @@ See `fio_trylock_group` for details.
 
 Unlocks a sub-lock group, no matter which thread owns which sub-lock.
 
+#### `fio_is_group_locked(fio_lock_i *, uint8_t group)`
+
+Returns 1 if the specified group-lock is engaged. Otherwise returns 0.
+
 #### `fio_trylock_full(fio_lock_i *lock)`
 
 Tries to lock all sub-locks. Returns 0 on success and 1 on failure.

diff --git a/fio-stl/000 core.h b/fio-stl/000 core.h
@@ -718,6 +718,9 @@ Spin-Locks
 #define FIO_LOCK_SUBLOCK(sub) ((uint8_t)(1U) << ((sub)&7))
 typedef volatile unsigned char fio_lock_i;
 
+#ifndef FIO___LOCK_RESCHDULE_EVERY_LOG
+#define FIO___LOCK_RESCHDULE_EVERY_LOG 8
+#endif
 /**
  * Tries to lock a group of sublocks.
  *
@@ -753,7 +756,7 @@ FIO_IFUNC uint8_t fio_trylock_group(fio_lock_i *lock, uint8_t group) {
 FIO_IFUNC void fio_lock_group(fio_lock_i *lock, uint8_t group) {
   size_t i = 0;
   while (fio_trylock_group(lock, group)) {
-    if ((i++ & 64)) {
+    if ((i++ & (1U << FIO___LOCK_RESCHDULE_EVERY_LOG))) {
       i = 0;
       FIO_THREAD_RESCHEDULE();
     }

diff --git a/fio-stl/000 core.md b/fio-stl/000 core.md
@@ -1427,11 +1427,9 @@ A spinlock type based on a volatile unsigned char.
 
 **Note**: the spinlock contains one main / default lock (`sub == 0`) and 7 sub-locks (`sub >= 1 && sub <= 7`), which could be managed:
 
-- Separately: using the `fio_lock_sublock`, `fio_trylock_sublock` and `fio_unlock_sublock` functions.
-- Jointly: using the `fio_trylock_group`, `fio_lock_group` and `fio_unlock_group` functions.
+- Separately / Jointly: using the `fio_trylock_group`, `fio_lock_group` and `fio_unlock_group` functions.
 - Collectively: using the `fio_trylock_full`, `fio_lock_full` and `fio_unlock_full` functions.
 
-
 #### `fio_lock(fio_lock_i *)`
 
 Busy waits for the default lock (sub-lock `0`) to become available.
@@ -1448,22 +1446,6 @@ Unlocks the default lock (sub-lock `0`), no matter which thread owns the lock.
 
 Returns 1 if the (main) lock is engaged. Otherwise returns 0.
 
-#### `fio_lock_sublock(fio_lock_i *, uint8_t sub)`
-
-Busy waits for a sub-lock to become available.
-
-#### `fio_trylock_sublock(fio_lock_i *, uint8_t sub)`
-
-Attempts to acquire the sub-lock. Returns 0 on success and 1 on failure.
-
-#### `fio_unlock_sublock(fio_lock_i *, uint8_t sub)`
-
-Unlocks the sub-lock, no matter which thread owns the lock.
-
-#### `fio_is_sublocked(fio_lock_i *, uint8_t sub)`
-
-Returns 1 if the specified sub-lock is engaged. Otherwise returns 0.
-
 #### `uint8_t fio_trylock_group(fio_lock_i *lock, const uint8_t group)`
 
 Tries to lock a group of sub-locks.
@@ -1492,6 +1474,10 @@ See `fio_trylock_group` for details.
 
 Unlocks a sub-lock group, no matter which thread owns which sub-lock.
 
+#### `fio_is_group_locked(fio_lock_i *, uint8_t group)`
+
+Returns 1 if the specified group-lock is engaged. Otherwise returns 0.
+
 #### `fio_trylock_full(fio_lock_i *lock)`
 
 Tries to lock all sub-locks. Returns 0 on success and 1 on failure.