log: improve the most common use case (#19242)

vlib/sync/sync_darwin.c.v

@@ -21,6 +21,7 @@ fn C.pthread_rwlock_init(voidptr, voidptr) int
 fn C.pthread_rwlock_rdlock(voidptr) int
 fn C.pthread_rwlock_wrlock(voidptr) int
 fn C.pthread_rwlock_unlock(voidptr) int
+fn C.pthread_rwlock_destroy(voidptr) int
 fn C.pthread_condattr_init(voidptr) int
 fn C.pthread_condattr_setpshared(voidptr, int) int
 fn C.pthread_condattr_destroy(voidptr) int
@@ -76,22 +77,29 @@ mut:
 	count u32
 }
 
+// new_mutex creates and initialises a new mutex instance on the heap, then returns a pointer to it.
 pub fn new_mutex() &Mutex {
 	mut m := &Mutex{}
 	m.init()
 	return m
 }
 
+// init initialises the mutex. It should be called once before the mutex is used,
+// since it creates the associated resources needed for the mutex to work properly.
+[inline]
 pub fn (mut m Mutex) init() {
 	C.pthread_mutex_init(&m.mutex, C.NULL)
 }
 
+// new_rwmutex creates a new read/write mutex instance on the heap, and returns a pointer to it.
 pub fn new_rwmutex() &RwMutex {
 	mut m := &RwMutex{}
 	m.init()
 	return m
 }
 
+// init initialises the RwMutex instance. It should be called once before the rw mutex is used,
+// since it creates the associated resources needed for the mutex to work properly.
 pub fn (mut m RwMutex) init() {
 	a := RwMutexAttr{}
 	C.pthread_rwlockattr_init(&a.attr)
@@ -101,45 +109,100 @@ pub fn (mut m RwMutex) init() {
 	C.pthread_rwlock_init(&m.mutex, &a.attr)
 }
 
-// @lock(), for *manual* mutex handling, since `lock` is a keyword
+// @lock locks the mutex instance (`lock` is a keyword).
+// If the mutex was already locked, it will block, till it is unlocked.
+[inline]
 pub fn (mut m Mutex) @lock() {
 	C.pthread_mutex_lock(&m.mutex)
 }
 
+// unlock unlocks the mutex instance. The mutex is released, and one of
+// the other threads, that were blocked, because they called @lock can continue.
+[inline]
 pub fn (mut m Mutex) unlock() {
 	C.pthread_mutex_unlock(&m.mutex)
 }
 
-// RwMutex has separate read- and write locks
+// destroy frees the resources associated with the mutex instance.
+// Note: the mutex itself is not freed.
+[inline]
+pub fn (mut m Mutex) destroy() {
+	res := C.pthread_mutex_destroy(&m.mutex)
+	if res != 0 {
+		cpanic(res)
+	}
+}
+
+// @rlock locks the given RwMutex instance for reading.
+// If the mutex was already locked, it will block, and will try to get the lock,
+// once the lock is released by another thread calling unlock.
+// Once it succeds, it returns.
+// Note: there may be several threads that are waiting for the same lock.
+// Note: RwMutex has separate read and write locks.
+[inline]
 pub fn (mut m RwMutex) @rlock() {
 	C.pthread_rwlock_rdlock(&m.mutex)
 }
 
+// @lock locks the given RwMutex instance for writing.
+// If the mutex was already locked, it will block, till it is unlocked,
+// then it will try to get the lock, and if it can, it will return, otherwise
+// it will continue waiting for the mutex to become unlocked.
+// Note: there may be several threads that are waiting for the same lock.
+// Note: RwMutex has separate read and write locks.
+[inline]
 pub fn (mut m RwMutex) @lock() {
 	C.pthread_rwlock_wrlock(&m.mutex)
 }
 
-// Windows SRWLocks have different function to unlock
-// So provide two functions here, too, to have a common interface
+// destroy frees the resources associated with the rwmutex instance.
+// Note: the mutex itself is not freed.
+[inline]
+pub fn (mut m RwMutex) destroy() {
+	res := C.pthread_rwlock_destroy(&m.mutex)
+	if res != 0 {
+		cpanic(res)
+	}
+}
+
+// runlock unlocks the RwMutex instance, locked for reading.
+// Note: Windows SRWLocks have different function to unlocking.
+// To have a common portable API, there are two methods for
+// unlocking here as well, even though that they do the same
+// on !windows platforms.
+[inline]
 pub fn (mut m RwMutex) runlock() {
 	C.pthread_rwlock_unlock(&m.mutex)
 }
 
+// unlock unlocks the RwMutex instance, locked for writing.
+// Note: Windows SRWLocks have different function to unlocking.
+// To have a common portable API, there are two methods for
+// unlocking here as well, even though that they do the same
+// on !windows platforms.
+[inline]
 pub fn (mut m RwMutex) unlock() {
 	C.pthread_rwlock_unlock(&m.mutex)
 }
 
+// new_semaphore creates a new initialised Semaphore instance on the heap, and returns a pointer to it.
+// The initial counter value of the semaphore is 0.
 [inline]
 pub fn new_semaphore() &Semaphore {
 	return new_semaphore_init(0)
 }
 
+// new_semaphore_init creates a new initialised Semaphore instance on the heap, and returns a pointer to it.
+// The `n` parameter can be used to set the initial counter value of the semaphore.
 pub fn new_semaphore_init(n u32) &Semaphore {
 	mut sem := &Semaphore{}
 	sem.init(n)
 	return sem
 }
 
+// init initialises the Semaphore instance with `n` as its initial counter value.
+// It should be called once before the semaphore is used, since it creates the associated
+// resources needed for the semaphore to work properly.
 pub fn (mut sem Semaphore) init(n u32) {
 	C.atomic_store_u32(&sem.count, n)
 	C.pthread_mutex_init(&sem.mtx, C.NULL)
@@ -150,6 +213,10 @@ pub fn (mut sem Semaphore) init(n u32) {
 	C.pthread_condattr_destroy(&attr.attr)
 }
 
+// post increases the counter of the semaphore by 1.
+// If the resulting counter value is > 0, and if there is a thread waiting
+// on the semaphore, the waiting thread will decrement the counter by 1, and
+// then will continue running. See also .wait() .
 pub fn (mut sem Semaphore) post() {
 	mut c := C.atomic_load_u32(&sem.count)
 	for c > 1 {
@@ -157,6 +224,7 @@ pub fn (mut sem Semaphore) post() {
 			return
 		}
 	}
+
 	C.pthread_mutex_lock(&sem.mtx)
 	c = C.atomic_fetch_add_u32(&sem.count, 1)
 	if c == 0 {
@@ -165,6 +233,11 @@ pub fn (mut sem Semaphore) post() {
 	C.pthread_mutex_unlock(&sem.mtx)
 }
 
+// wait will just decrement the semaphore count, if it was positive.
+// It it was not positive, it will waits for the semaphore count to reach a positive number.
+// When that happens, it will decrease the semaphore count, and will return.
+// In effect, it allows you to block threads, until the semaphore, is posted by another thread.
+// See also .post() .
 pub fn (mut sem Semaphore) wait() {
 	mut c := C.atomic_load_u32(&sem.count)
 	for c > 0 {
@@ -172,9 +245,9 @@ pub fn (mut sem Semaphore) wait() {
 			return
 		}
 	}
+
 	C.pthread_mutex_lock(&sem.mtx)
 	c = C.atomic_load_u32(&sem.count)
-
 	outer: for {
 		if c == 0 {
 			C.pthread_cond_wait(&sem.cond, &sem.mtx)
@@ -192,6 +265,10 @@ pub fn (mut sem Semaphore) wait() {
 	C.pthread_mutex_unlock(&sem.mtx)
 }
 
+// try_wait tries to decrease the semaphore count by 1, if it was positive.
+// If it succeeds in that, it returns true, otherwise it returns false.
+// Note: try_wait should return as fast as possible so error handling is only
+// done when debugging
 pub fn (mut sem Semaphore) try_wait() bool {
 	mut c := C.atomic_load_u32(&sem.count)
 	for c > 0 {
@@ -202,6 +279,8 @@ pub fn (mut sem Semaphore) try_wait() bool {
 	return false
 }
 
+// timed_wait is similar to .wait(), but it also accepts a timeout duration,
+// thus it can return false early, if the timeout passed before the semaphore was posted.
 pub fn (mut sem Semaphore) timed_wait(timeout time.Duration) bool {
 	mut c := C.atomic_load_u32(&sem.count)
 	for c > 0 {
@@ -235,13 +314,15 @@ pub fn (mut sem Semaphore) timed_wait(timeout time.Duration) bool {
 	return res == 0
 }
 
+// destroy frees the resources associated with the Semaphore instance.
+// Note: the semaphore instance itself is not freed.
 pub fn (mut sem Semaphore) destroy() {
 	mut res := C.pthread_cond_destroy(&sem.cond)
-	if res == 0 {
-		res = C.pthread_mutex_destroy(&sem.mtx)
-		if res == 0 {
-			return
-		}
+	if res != 0 {
+		cpanic(res)
+	}
+	res = C.pthread_mutex_destroy(&sem.mtx)
+	if res != 0 {
+		cpanic(res)
 	}
-	panic(unsafe { tos_clone(&u8(C.strerror(res))) })
 }