darwin: remove duplicated and desynched documentation

src/darwin/thread.c

@@ -138,8 +138,6 @@ void vlc_mutex_init( vlc_mutex_t *p_mutex )
     pthread_mutexattr_destroy( &attr );
 }
 
-/* Initializes a recursive mutex.
- * warning: This is strongly discouraged. Please use normal mutexes. */
 void vlc_mutex_init_recursive( vlc_mutex_t *p_mutex )
 {
     pthread_mutexattr_t attr;
@@ -153,10 +151,6 @@ void vlc_mutex_init_recursive( vlc_mutex_t *p_mutex )
 }
 
 
-/* Destroys a mutex. The mutex must not be locked.
- *
- * parameter: p_mutex mutex to destroy
- * returns: always succeeds */
 void vlc_mutex_destroy (vlc_mutex_t *p_mutex)
 {
     int val = pthread_mutex_destroy( p_mutex );
@@ -170,7 +164,6 @@ void vlc_mutex_destroy (vlc_mutex_t *p_mutex)
 #  define RUNNING_ON_VALGRIND (0)
 # endif
 
-/* Asserts that a mutex is locked by the calling thread. */
 void vlc_assert_locked (vlc_mutex_t *p_mutex)
 {
     if (RUNNING_ON_VALGRIND > 0)
@@ -179,33 +172,12 @@ void vlc_assert_locked (vlc_mutex_t *p_mutex)
 }
 #endif
 
-/* Acquires a mutex. If needed, waits for any other thread to release it.
- * Beware of deadlocks when locking multiple mutexes at the same time,
- * or when using mutexes from callbacks.
- * This function is not a cancellation-point.
- *
- * parameter: p_mutex mutex initialized with vlc_mutex_init() or
- *                vlc_mutex_init_recursive()
- */
 void vlc_mutex_lock (vlc_mutex_t *p_mutex)
 {
     int val = pthread_mutex_lock( p_mutex );
     VLC_THREAD_ASSERT ("locking mutex");
 }
 
-/* Acquires a mutex if and only if it is not currently held by another thread.
- * This function never sleeps and can be used in delay-critical code paths.
- * This function is not a cancellation-point.
- *
- * BEWARE: If this function fails, then the mutex is held... by another
- * thread. The calling thread must deal with the error appropriately. That
- * typically implies postponing the operations that would have required the
- * mutex. If the thread cannot defer those operations, then it must use
- * vlc_mutex_lock(). If in doubt, use vlc_mutex_lock() instead.
- *
- * parameter: p_mutex mutex initialized with vlc_mutex_init() or
- *                vlc_mutex_init_recursive()
- * returns: 0 if the mutex could be acquired, an error code otherwise. */
 int vlc_mutex_trylock (vlc_mutex_t *p_mutex)
 {
     int val = pthread_mutex_trylock( p_mutex );
@@ -215,8 +187,6 @@ int vlc_mutex_trylock (vlc_mutex_t *p_mutex)
     return val;
 }
 
-/* Release a mutex (or crashes if the mutex is not locked by the caller).
- * parameter p_mutex mutex locked with vlc_mutex_lock(). */
 void vlc_mutex_unlock (vlc_mutex_t *p_mutex)
 {
     int val = pthread_mutex_unlock( p_mutex );
@@ -229,7 +199,6 @@ enum
     VLC_CLOCK_REALTIME,
 };
 
-/* Initialize a condition variable. */
 void vlc_cond_init (vlc_cond_t *p_condvar)
 {
     if (unlikely(pthread_cond_init (&p_condvar->cond, NULL)))
@@ -237,9 +206,6 @@ void vlc_cond_init (vlc_cond_t *p_condvar)
     p_condvar->clock = VLC_CLOCK_MONOTONIC;
 }
 
-/* Initialize a condition variable.
- * Contrary to vlc_cond_init(), the wall clock will be used as a reference for
- * the vlc_cond_timedwait() time-out parameter. */
 void vlc_cond_init_daytime (vlc_cond_t *p_condvar)
 {
     if (unlikely(pthread_cond_init (&p_condvar->cond, NULL)))
@@ -248,9 +214,6 @@ void vlc_cond_init_daytime (vlc_cond_t *p_condvar)
 
 }
 
-/* Destroys a condition variable. No threads shall be waiting or signaling the
- * condition.
- * parameter: p_condvar condition variable to destroy */
 void vlc_cond_destroy (vlc_cond_t *p_condvar)
 {
     int val = pthread_cond_destroy (&p_condvar->cond);
@@ -279,69 +242,23 @@ void vlc_cond_destroy (vlc_cond_t *p_condvar)
     VLC_THREAD_ASSERT ("destroying condition");
 }
 
-/* Wake up one thread waiting on a condition variable, if any.
- * parameter: p_condvar condition variable */
 void vlc_cond_signal (vlc_cond_t *p_condvar)
 {
     int val = pthread_cond_signal (&p_condvar->cond);
     VLC_THREAD_ASSERT ("signaling condition variable");
 }
 
-/* Wake up all threads (if any) waiting on a condition variable.
- * parameter: p_cond condition variable */
 void vlc_cond_broadcast (vlc_cond_t *p_condvar)
 {
     pthread_cond_broadcast (&p_condvar->cond);
 }
 
-/* Wait for a condition variable. The calling thread will be suspended until
- * another thread calls vlc_cond_signal() or vlc_cond_broadcast() on the same
- * condition variable, the thread is cancelled with vlc_cancel(), or the
- * system causes a "spurious" unsolicited wake-up.
- *
- * A mutex is needed to wait on a condition variable. It must <b>not</b> be
- * a recursive mutex. Although it is possible to use the same mutex for
- * multiple condition, it is not valid to use different mutexes for the same
- * condition variable at the same time from different threads.
- *
- * In case of thread cancellation, the mutex is always locked before
- * cancellation proceeds.
- *
- * The canonical way to use a condition variable to wait for event foobar is:
- sample code:
-   vlc_mutex_lock (&lock);
-   mutex_cleanup_push (&lock); // release the mutex in case of cancellation
-
-   while (!foobar)
-       vlc_cond_wait (&wait, &lock);
-
-   --- foobar is now true, do something about it here --
-
-   vlc_cleanup_run (); // release the mutex
- *
- * 1st parameter: p_condvar condition variable to wait on
- * 2nd parameter: p_mutex mutex which is unlocked while waiting,
- *                then locked again when waking up. */
 void vlc_cond_wait (vlc_cond_t *p_condvar, vlc_mutex_t *p_mutex)
 {
     int val = pthread_cond_wait (&p_condvar->cond, p_mutex);
     VLC_THREAD_ASSERT ("waiting on condition");
 }
 
-/* Wait for a condition variable up to a certain date.
- * This works like vlc_cond_wait(), except for the additional time-out.
- *
- * If the variable was initialized with vlc_cond_init(), the timeout has the
- * same arbitrary origin as mdate(). If the variable was initialized with
- * vlc_cond_init_daytime(), the timeout is expressed from the Unix epoch.
- *
- * 1st parameter: p_condvar condition variable to wait on
- * 2nd parameter: p_mutex mutex which is unlocked while waiting,
- *                then locked again when waking up.
- * 3rd parameter: deadline <b>absolute</b> timeout
- *
- * returns 0 if the condition was signaled, an error code in case of timeout.
- */
 int vlc_cond_timedwait (vlc_cond_t *p_condvar, vlc_mutex_t *p_mutex,
                         mtime_t deadline)
 {
@@ -399,7 +316,6 @@ void vlc_sem_init (vlc_sem_t *sem, unsigned value)
         abort ();
 }
 
-/* Destroy a semaphore. */
 void vlc_sem_destroy (vlc_sem_t *sem)
 {
     int val;
@@ -412,8 +328,6 @@ void vlc_sem_destroy (vlc_sem_t *sem)
     VLC_THREAD_ASSERT ("destroying semaphore");
 }
 
-/* Increment the value of a semaphore.
- * returns 0 on success, EOVERFLOW in case of integer overflow */
 int vlc_sem_post (vlc_sem_t *sem)
 {
     int val;
@@ -428,8 +342,6 @@ int vlc_sem_post (vlc_sem_t *sem)
     return val;
 }
 
-/* Atomically wait for the semaphore to become non-zero (if needed),
- * then decrements it. */
 void vlc_sem_wait (vlc_sem_t *sem)
 {
     int val;
@@ -442,52 +354,36 @@ void vlc_sem_wait (vlc_sem_t *sem)
     VLC_THREAD_ASSERT ("locking semaphore");
 }
 
-/* Initialize a read/write lock. */
 void vlc_rwlock_init (vlc_rwlock_t *lock)
 {
     if (unlikely(pthread_rwlock_init (lock, NULL)))
         abort ();
 }
 
-/* Destroy an initialized unused read/write lock. */
 void vlc_rwlock_destroy (vlc_rwlock_t *lock)
 {
     int val = pthread_rwlock_destroy (lock);
     VLC_THREAD_ASSERT ("destroying R/W lock");
 }
 
-/* Acquire a read/write lock for reading. Recursion is allowed.
- * Attention: This function may be a cancellation point. */
 void vlc_rwlock_rdlock (vlc_rwlock_t *lock)
 {
     int val = pthread_rwlock_rdlock (lock);
     VLC_THREAD_ASSERT ("acquiring R/W lock for reading");
 }
 
-/* Acquire a read/write lock for writing. Recursion is not allowed.
- * Attention: This function may be a cancellation point. */
 void vlc_rwlock_wrlock (vlc_rwlock_t *lock)
 {
     int val = pthread_rwlock_wrlock (lock);
     VLC_THREAD_ASSERT ("acquiring R/W lock for writing");
 }
 
-/* Release a read/write lock. */
 void vlc_rwlock_unlock (vlc_rwlock_t *lock)
 {
     int val = pthread_rwlock_unlock (lock);
     VLC_THREAD_ASSERT ("releasing R/W lock");
 }
 
-/* Allocates a thread-specific variable.
- * 1st parameter: key where to store the thread-specific variable handle
- * 2nd parameter: destr a destruction callback. It is called whenever a thread
- * exits and the thread-specific variable has a non-NULL value.
- * returns 0 on success, a system error code otherwise.
- *
- * This function can actually fail because there is a fixed limit on the number
- * of thread-specific variable in a process on most systems.
- */
 int vlc_threadvar_create (vlc_threadvar_t *key, void (*destr) (void *))
 {
     return pthread_key_create (key, destr);
@@ -498,20 +394,11 @@ void vlc_threadvar_delete (vlc_threadvar_t *p_tls)
     pthread_key_delete (*p_tls);
 }
 
-/* Set a thread-specific variable.
- * 1st parameter: key thread-local variable key
- *                (created with vlc_threadvar_create())
- * 2nd parameter: value new value for the variable for the calling thread
- * returns 0 on success, a system error code otherwise. */
 int vlc_threadvar_set (vlc_threadvar_t key, void *value)
 {
     return pthread_setspecific (key, value);
 }
 
-/* Get the value of a thread-local variable for the calling thread.
- * This function cannot fail.
- * returns the value associated with the given variable for the calling
- * or NULL if there is no value. */
 void *vlc_threadvar_get (vlc_threadvar_t key)
 {
     return pthread_getspecific (key);
@@ -537,22 +424,11 @@ void vlc_threads_setup (libvlc_int_t *p_libvlc)
     vlc_mutex_unlock (&lock);
 }
 
-
 static int vlc_clone_attr (vlc_thread_t *th, pthread_attr_t *attr,
                            void *(*entry) (void *), void *data, int priority)
 {
     int ret;
 
-    /* Block the signals that signals interface plugin handles.
-     * If the LibVLC caller wants to handle some signals by itself, it should
-     * block these before whenever invoking LibVLC. And it must obviously not
-     * start the VLC signals interface plugin.
-     *
-     * LibVLC will normally ignore any interruption caused by an asynchronous
-     * signal during a system call. But there may well be some buggy cases
-     * where it fails to handle EINTR (bug reports welcome). Some underlying
-     * libraries might also not handle EINTR properly.
-     */
     sigset_t oldset;
     {
         sigset_t set;
@@ -568,18 +444,6 @@ static int vlc_clone_attr (vlc_thread_t *th, pthread_attr_t *attr,
 
     (void) priority;
 
-    /* The thread stack size.
-     * The lower the value, the less address space per thread, the highest
-     * maximum simultaneous threads per process. Too low values will cause
-     * stack overflows and weird crashes. Set with caution. Also keep in mind
-     * that 64-bits platforms consume more stack than 32-bits one.
-     *
-     * Thanks to on-demand paging, thread stack size only affects address space
-     * consumption. In terms of memory, threads only use what they need
-     * (rounded up to the page boundary).
-     *
-     * For example, on Linux i386, the default is 2 mega-bytes, which supports
-     * about 320 threads per processes. */
 #define VLC_STACKSIZE (128 * sizeof (void *) * 1024)
 
 #ifdef VLC_STACKSIZE
@@ -593,17 +457,6 @@ static int vlc_clone_attr (vlc_thread_t *th, pthread_attr_t *attr,
     return ret;
 }
 
-/* Create and start a new thread.
- *
- * The thread must be joined with vlc_join() to reclaim resources when it is 
- * not needed anymore.
- *
- * 1st parameter: th [OUT] pointer to write the handle of the created thread to
- *                 (mandatory, must be non-NULL)
- * 2nd parameter: entry entry point for the thread
- * 3rd parameter: data data parameter given to the entry point
- * 4th parameter: priority thread priority value
- * returns 0 on success, a standard error code on error. */
 int vlc_clone (vlc_thread_t *th, void *(*entry) (void *), void *data,
                int priority)
 {
@@ -613,50 +466,12 @@ int vlc_clone (vlc_thread_t *th, void *(*entry) (void *), void *data,
     return vlc_clone_attr (th, &attr, entry, data, priority);
 }
 
-/* Wait for a thread to complete (if needed), then destroys it.
- * This is a cancellation point; in case of cancellation, the join does _not_
- * occur.
- * 
- * WARNING: A thread cannot join itself (normally VLC will abort if this is
- * attempted). Also, a detached thread cannot be joined.
- *
- * 1st parameter: handle thread handle
- * 2nd parameter: p_result - pointer to write the thread return value or NULL
- */
 void vlc_join (vlc_thread_t handle, void **result)
 {
     int val = pthread_join (handle, result);
     VLC_THREAD_ASSERT ("joining thread");
 }
 
-/* Create and start a new detached thread.
- * A detached thread cannot be joined. Its resources will be automatically
- * released whenever the thread exits (in particular, its call stack will be
- * reclaimed).
- *
- * Detached thread are particularly useful when some work needs to be done
- * asynchronously, that is likely to be completed much earlier than the thread
- * can practically be joined. In this case, thread detach can spare memory.
- *
- * A detached thread may be cancelled, so as to expedite its termination.
- * Be extremely careful if you do this: while a normal joinable thread can
- * safely be cancelled after it has already exited, cancelling an already
- * exited detached thread is undefined: The thread handle would is destroyed
- * immediately when the detached thread exits. So you need to ensure that the
- * detached thread is still running before cancellation is attempted.
- *
- * WARNING: Care must be taken that any resources used by the detached thread
- * remains valid until the thread completes.
- *
- * Attention: A detached thread must eventually exit just like another other
- * thread. In practice, LibVLC will wait for detached threads to exit before
- * it unloads the plugins.
- *
- * 1st parameter: th [OUT] pointer to hold the thread handle, or NULL
- * 2nd parameter: entry entry point for the thread
- * 3rd parameter: data data parameter given to the entry point
- * 4th parameter: priority thread priority value
- * returns 0 on success, a standard error code on error. */
 int vlc_clone_detach (vlc_thread_t *th, void *(*entry) (void *), void *data,
                       int priority)
 {
@@ -677,22 +492,11 @@ int vlc_set_priority (vlc_thread_t th, int priority)
     return VLC_SUCCESS;
 }
 
-/* Marks a thread as cancelled. Next time the target thread reaches a
- * cancellation point (while not having disabled cancellation), it will
- * run its cancellation cleanup handler, the thread variable destructors, and
- * terminate. vlc_join() must be used afterward regardless of a thread being
- * cancelled or not. */
 void vlc_cancel (vlc_thread_t thread_id)
 {
     pthread_cancel (thread_id);
 }
 
-/* Save the current cancellation state (enabled or disabled), then disable
- * cancellation for the calling thread.
- * This function must be called before entering a piece of code that is not
- * cancellation-safe, unless it can be proven that the calling thread will not
- * be cancelled.
- * returns Previous cancellation state (opaque value for vlc_restorecancel()). */
 int vlc_savecancel (void)
 {
     int state;
@@ -702,15 +506,12 @@ int vlc_savecancel (void)
     return state;
 }
 
-/* Restore the cancellation state for the calling thread.
- * parameter: previous state as returned by vlc_savecancel(). */
 void vlc_restorecancel (int state)
 {
 #ifndef NDEBUG
     int oldstate, val;
 
     val = pthread_setcancelstate (state, &oldstate);
-    /* This should fail if an invalid value for given for state */
     VLC_THREAD_ASSERT ("restoring cancellation");
 
     if (unlikely(oldstate != PTHREAD_CANCEL_DISABLE))
@@ -721,11 +522,6 @@ void vlc_restorecancel (int state)
 #endif
 }
 
-/* Issues an explicit deferred cancellation point.
- * This has no effect if thread cancellation is disabled.
- * This can be called when there is a rather slow non-sleeping operation.
- * This is also used to force a cancellation point in a function that would
- * otherwise "not always" be a one (block_FifoGet() is an example). */
 void vlc_testcancel (void)
 {
     pthread_testcancel ();
@@ -737,18 +533,6 @@ void vlc_control_cancel (int cmd, ...)
     vlc_assert_unreachable ();
 }
 
-/* Precision monotonic clock.
- *
- * In principles, the clock has a precision of 1 MHz. But the actual resolution
- * may be much lower, especially when it comes to sleeping with mwait() or
- * msleep(). Most general-purpose operating systems provide a resolution of
- * only 100 to 1000 Hz.
- *
- * WARNING: The origin date (time value "zero") is not specified. It is
- * typically the time the kernel started, but this is platform-dependent.
- * If you need wall clock time, use gettimeofday() instead.
- *
- * returns a timestamp in microseconds. */
 mtime_t mdate (void)
 {
     vlc_clock_setup();
@@ -767,8 +551,6 @@ mtime_t mdate (void)
 }
 
 #undef mwait
-/* Wait until a deadline (possibly later due to OS scheduling).
- * parameter: deadline timestamp to wait for (see mdate()) */
 void mwait (mtime_t deadline)
 {
     deadline -= mdate ();
@@ -777,8 +559,6 @@ void mwait (mtime_t deadline)
 }
 
 #undef msleep
-/* Wait for an interval of time.
- * parameter: delay how long to wait (in microseconds) */
 void msleep (mtime_t delay)
 {
     struct timespec ts = mtime_to_ts (delay);
@@ -789,8 +569,6 @@ void msleep (mtime_t delay)
         assert (errno == EINTR);
 }
 
-/* Count CPUs.
- * returns the number of available (logical) CPUs. */
 unsigned vlc_GetCPUCount(void)
 {
     return sysconf(_SC_NPROCESSORS_CONF);