thread.c File Reference

Include dependency graph for thread.c:

Macros
#define	_POSIX_TIMERS   (-1)
#define	_POSIX_CLOCK_SELECTION   (-1)
#define	_POSIX_MONOTONIC_CLOCK   (-1)
#define	vlc_clock_setup()   (void)0
#define	VLC_THREAD_ASSERT(action)
#define	RUNNING_ON_VALGRIND   (0)
#define	VLC_STACKSIZE   (128 * sizeof (void *) * 1024)

Functions
static struct timespec	mtime_to_ts (mtime_t date)
void	vlc_trace (const char *fn, const char *file, unsigned line)
	Print a backtrace to the standard error for debugging purpose.
static unsigned long	vlc_threadid (void)
static void	vlc_thread_fatal (const char *action, int error, const char *function, const char *file, unsigned line)
	Reports a fatal error from the threading layer, for debugging purposes.
void	vlc_mutex_init (vlc_mutex_t *p_mutex)
	Initializes a fast mutex.
void	vlc_mutex_init_recursive (vlc_mutex_t *p_mutex)
	Initializes a recursive mutex.
void	vlc_mutex_destroy (vlc_mutex_t *p_mutex)
	Destroys a mutex.
void	vlc_assert_locked (vlc_mutex_t *p_mutex)
	Asserts that a mutex is locked by the calling thread.
void	vlc_mutex_lock (vlc_mutex_t *p_mutex)
	Acquires a mutex.
int	vlc_mutex_trylock (vlc_mutex_t *p_mutex)
	Acquires a mutex if and only if it is not currently held by another thread.
void	vlc_mutex_unlock (vlc_mutex_t *p_mutex)
	Releases a mutex (or crashes if the mutex is not locked by the caller).
void	vlc_cond_init (vlc_cond_t *p_condvar)
	Initializes a condition variable.
void	vlc_cond_init_daytime (vlc_cond_t *p_condvar)
	Initializes a condition variable.
void	vlc_cond_destroy (vlc_cond_t *p_condvar)
	Destroys a condition variable.
void	vlc_cond_signal (vlc_cond_t *p_condvar)
	Wakes up one thread waiting on a condition variable, if any.
void	vlc_cond_broadcast (vlc_cond_t *p_condvar)
	Wakes up all threads (if any) waiting on a condition variable.
void	vlc_cond_wait (vlc_cond_t *p_condvar, vlc_mutex_t *p_mutex)
	Waits for a condition variable.
int	vlc_cond_timedwait (vlc_cond_t *p_condvar, vlc_mutex_t *p_mutex, mtime_t deadline)
	Waits for a condition variable up to a certain date.
void	vlc_sem_init (vlc_sem_t *sem, unsigned value)
	Initializes a semaphore.
void	vlc_sem_destroy (vlc_sem_t *sem)
	Destroys a semaphore.
int	vlc_sem_post (vlc_sem_t *sem)
	Increments the value of a semaphore.
void	vlc_sem_wait (vlc_sem_t *sem)
	Atomically wait for the semaphore to become non-zero (if needed), then decrements it.
void	vlc_rwlock_init (vlc_rwlock_t *lock)
	Initializes a read/write lock.
void	vlc_rwlock_destroy (vlc_rwlock_t *lock)
	Destroys an initialized unused read/write lock.
void	vlc_rwlock_rdlock (vlc_rwlock_t *lock)
	Acquires a read/write lock for reading.
void	vlc_rwlock_wrlock (vlc_rwlock_t *lock)
	Acquires a read/write lock for writing.
void	vlc_rwlock_unlock (vlc_rwlock_t *lock)
	Releases a read/write lock.
int	vlc_threadvar_create (vlc_threadvar_t *key, void(*destr)(void *))
	Allocates a thread-specific variable.
void	vlc_threadvar_delete (vlc_threadvar_t *p_tls)
int	vlc_threadvar_set (vlc_threadvar_t key, void *value)
	Sets a thread-specific variable.
void *	vlc_threadvar_get (vlc_threadvar_t key)
	Gets the value of a thread-local variable for the calling thread.
void	vlc_threads_setup (libvlc_int_t *p_libvlc)
static int	vlc_clone_attr (vlc_thread_t *th, pthread_attr_t *attr, void *(*entry)(void *), void *data, int priority)
int	vlc_clone (vlc_thread_t *th, void *(*entry)(void *), void *data, int priority)
	Creates and starts new thread.
void	vlc_join (vlc_thread_t handle, void **result)
	Waits for a thread to complete (if needed), then destroys it.
int	vlc_clone_detach (vlc_thread_t *th, void *(*entry)(void *), void *data, int priority)
	Creates and starts new detached thread.
int	vlc_set_priority (vlc_thread_t th, int priority)
void	vlc_cancel (vlc_thread_t thread_id)
	Marks a thread as cancelled.
int	vlc_savecancel (void)
	Save the current cancellation state (enabled or disabled), then disable cancellation for the calling thread.
void	vlc_restorecancel (int state)
	Restore the cancellation state for the calling thread.
void	vlc_testcancel (void)
	Issues an explicit deferred cancellation point.
void	vlc_control_cancel (int cmd,...)
mtime_t	mdate (void)
	Precision monotonic clock.
void	mwait ((mtime_t deadline))
	Waits until a deadline (possibly later due to OS scheduling).
void	msleep ((mtime_t delay))
	Waits for an interval of time.
unsigned	vlc_GetCPUCount (void)
	Count CPUs.

Variables
static bool	rt_priorities = false
static int	rt_offset

Macro Definition Documentation

#define _POSIX_CLOCK_SELECTION   (-1)

#define _POSIX_MONOTONIC_CLOCK   (-1)

#define _POSIX_TIMERS   (-1)

#define RUNNING_ON_VALGRIND   (0)

Referenced by module_Unload(), and vlc_assert_locked().

#define vlc_clock_setup

(

)

(void)0

Referenced by mdate(), msleep(), mwait(), and vlc_cond_init().

#define VLC_STACKSIZE   (128 * sizeof (void *) * 1024)

Referenced by vlc_clone_attr().

#define VLC_THREAD_ASSERT

(

action

)

Value:

if (unlikely(val)) \
        vlc_thread_fatal (action, val, __func__, __FILE__, __LINE__)

Referenced by vlc_cond_destroy(), vlc_cond_signal(), vlc_cond_timedwait(), vlc_cond_wait(), vlc_join(), vlc_mutex_destroy(), vlc_mutex_lock(), vlc_mutex_trylock(), vlc_mutex_unlock(), vlc_restorecancel(), vlc_rwlock_destroy(), vlc_rwlock_rdlock(), vlc_rwlock_unlock(), vlc_rwlock_wrlock(), vlc_savecancel(), vlc_sem_destroy(), vlc_sem_post(), and vlc_sem_wait().

Function Documentation

mtime_t mdate

(

void

)

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.

References unlikely, and vlc_clock_setup.

void msleep

(

(mtime_t delay)

)

Waits for an interval of time.

Parameters

delay

how long to wait (in microseconds)

References mtime_to_ts(), and vlc_clock_setup.

static struct timespec mtime_to_ts ( mtime_t  date )

staticread

References CLOCK_FREQ, and lldiv().

Referenced by msleep(), mwait(), and vlc_cond_timedwait().

void mwait

(

(mtime_t deadline)

)

Waits until a deadline (possibly later due to OS scheduling).

Parameters

deadline

timestamp to wait for (see mdate())

References mdate(), msleep, mtime_to_ts(), and vlc_clock_setup.

void vlc_assert_locked

(

vlc_mutex_t *

p_mutex

)

Asserts that a mutex is locked by the calling thread.

References RUNNING_ON_VALGRIND.

void vlc_cancel

(

vlc_thread_t

thread_id

)

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.

int vlc_clone	(	vlc_thread_t *	th,
		void *(*)(void *)	entry,
		void *	data,
		int	priority
	)

Creates and starts new thread.

The thread must be joined with vlc_join() to reclaim resources when it is not needed anymore.

Parameters

th	[OUT] pointer to write the handle of the created thread to (mandatory, must be non-NULL)
entry	entry point for the thread
data	data parameter given to the entry point
priority	thread priority value

Returns

0 on success, a standard error code on error.

References vlc_clone_attr().

static int vlc_clone_attr ( vlc_thread_t *  th, pthread_attr_t *  attr, void *(*)(void *)  entry, void *  data, int  priority  )

static

References rt_offset, rt_priorities, and VLC_STACKSIZE.

Referenced by vlc_clone(), and vlc_clone_detach().

int vlc_clone_detach	(	vlc_thread_t *	th,
		void *(*)(void *)	entry,
		void *	data,
		int	priority
	)

Creates and starts 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.

Note

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.

Parameters

th	[OUT] pointer to hold the thread handle, or NULL
entry	entry point for the thread
data	data parameter given to the entry point
priority	thread priority value

Returns

0 on success, a standard error code on error.

References vlc_clone_attr().

void vlc_cond_broadcast

(

vlc_cond_t *

p_condvar

)

Wakes up all threads (if any) waiting on a condition variable.

Parameters

p_cond

condition variable

void vlc_cond_destroy

(

vlc_cond_t *

p_condvar

)

Destroys a condition variable.

No threads shall be waiting or signaling the condition.

Parameters

p_condvar

condition variable to destroy

References VLC_THREAD_ASSERT.

void vlc_cond_init

(

vlc_cond_t *

p_condvar

)

Initializes a condition variable.

References unlikely, and vlc_clock_setup.

void vlc_cond_init_daytime

(

vlc_cond_t *

p_condvar

)

Initializes 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.

References unlikely.

void vlc_cond_signal

(

vlc_cond_t *

p_condvar

)

Wakes up one thread waiting on a condition variable, if any.

Parameters

p_condvar

condition variable

References VLC_THREAD_ASSERT.

int vlc_cond_timedwait	(	vlc_cond_t *	p_condvar,
		vlc_mutex_t *	p_mutex,
		mtime_t	deadline
	)

Waits 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.

Parameters

p_condvar	condition variable to wait on
p_mutex	mutex which is unlocked while waiting, then locked again when waking up.
deadline	absolute timeout

Returns

0 if the condition was signaled, an error code in case of timeout.

References mtime_to_ts(), and VLC_THREAD_ASSERT.

void vlc_cond_wait	(	vlc_cond_t *	p_condvar,
		vlc_mutex_t *	p_mutex
	)

Waits 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 not 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:

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

Parameters

p_condvar	condition variable to wait on
p_mutex	mutex which is unlocked while waiting, then locked again when waking up.
deadline	absolute timeout

References VLC_THREAD_ASSERT.

void vlc_control_cancel	(	int	cmd,
			...
	)

unsigned vlc_GetCPUCount

(

void

)

Count CPUs.

Returns

number of available (logical) CPUs.

References count, and unlikely.

void vlc_join	(	vlc_thread_t	handle,
		void **	result
	)

Waits 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.

Parameters

handle	thread handle
p_result	[OUT] pointer to write the thread return value or NULL

References VLC_THREAD_ASSERT.

void vlc_mutex_destroy

(

vlc_mutex_t *

p_mutex

)

Destroys a mutex.

The mutex must not be locked.

Parameters

p_mutex

mutex to destroy

Returns

always succeeds

References VLC_THREAD_ASSERT.

void vlc_mutex_init

(

vlc_mutex_t *

p_mutex

)

Initializes a fast mutex.

References unlikely.

void vlc_mutex_init_recursive

(

vlc_mutex_t *

p_mutex

)

Initializes a recursive mutex.

Warning

This is strongly discouraged. Please use normal mutexes.

References unlikely.

void vlc_mutex_lock

(

vlc_mutex_t *

p_mutex

)

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.

Parameters

p_mutex

mutex initialized with vlc_mutex_init() or vlc_mutex_init_recursive()

References VLC_THREAD_ASSERT.

int vlc_mutex_trylock

(

vlc_mutex_t *

p_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.

Parameters

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.

References VLC_THREAD_ASSERT.

void vlc_mutex_unlock

(

vlc_mutex_t *

p_mutex

)

Releases a mutex (or crashes if the mutex is not locked by the caller).

Parameters

p_mutex

mutex locked with vlc_mutex_lock().

References VLC_THREAD_ASSERT.

void vlc_restorecancel

(

int

state

)

Restore the cancellation state for the calling thread.

Parameters

state

previous state as returned by vlc_savecancel().

Returns

Nothing, always succeeds.

References unlikely, VLC_THREAD_ASSERT, and vlc_thread_fatal().

void vlc_rwlock_destroy

(

vlc_rwlock_t *

lock

)

Destroys an initialized unused read/write lock.

References VLC_THREAD_ASSERT.

Referenced by _DLL_InitTerm(), and DllMain().

void vlc_rwlock_init

(

vlc_rwlock_t *

lock

)

Initializes a read/write lock.

References unlikely.

Referenced by _DLL_InitTerm(), and DllMain().

void vlc_rwlock_rdlock

(

vlc_rwlock_t *

lock

)

Acquires a read/write lock for reading.

Recursion is allowed.

Note

This function may be a point of cancellation.

References VLC_THREAD_ASSERT.

Referenced by config_AutoSaveConfigFile(), config_GetFloat(), config_GetInt(), config_GetPsz(), config_SaveConfigFile(), and vlc_vaLog().

void vlc_rwlock_unlock

(

vlc_rwlock_t *

lock

)

Releases a read/write lock.

References VLC_THREAD_ASSERT.

Referenced by config_AutoSaveConfigFile(), config_GetFloat(), config_GetInt(), config_GetPsz(), config_LoadConfigFile(), config_PutFloat(), config_PutInt(), config_PutPsz(), config_ResetAll(), config_SaveConfigFile(), vlc_Subscribe(), vlc_Unsubscribe(), and vlc_vaLog().

void vlc_rwlock_wrlock

(

vlc_rwlock_t *

lock

)

Acquires a read/write lock for writing.

Recursion is not allowed.

Note

This function may be a point of cancellation.

References VLC_THREAD_ASSERT.

Referenced by config_LoadConfigFile(), config_PutFloat(), config_PutInt(), config_PutPsz(), config_ResetAll(), vlc_Subscribe(), and vlc_Unsubscribe().

int vlc_savecancel

(

void

)

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()).

References VLC_THREAD_ASSERT.

void vlc_sem_destroy

(

vlc_sem_t *

sem

)

Destroys a semaphore.

Referenced by vlc_join(), and vlm_OnMediaUpdate().

void vlc_sem_init	(	vlc_sem_t *	sem,
		unsigned	value
	)

Initializes a semaphore.

Referenced by vlc_clone_attr(), and vlm_OnMediaUpdate().

int vlc_sem_post

(

vlc_sem_t *

sem

)

Increments the value of a semaphore.

Returns

0 on success, EOVERFLOW in case of integer overflow

Referenced by finish_joinable_thread(), and InputEventPreparse().

void vlc_sem_wait

(

vlc_sem_t *

sem

)

Atomically wait for the semaphore to become non-zero (if needed), then decrements it.

Referenced by vlc_join(), and vlm_OnMediaUpdate().

int vlc_set_priority	(	vlc_thread_t	th,
		int	priority
	)

< No error

References rt_offset, rt_priorities, VLC_EGENERIC, and VLC_SUCCESS.

void vlc_testcancel

(

void

)

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).

static void vlc_thread_fatal ( const char *  action, int  error, const char *  function, const char *  file, unsigned  line  )

static

Reports a fatal error from the threading layer, for debugging purposes.

References msg, vlc_restorecancel(), vlc_savecancel(), vlc_threadid(), and vlc_trace().

Referenced by vlc_restorecancel().

static unsigned long vlc_threadid ( void  )

inlinestatic

Referenced by vlc_thread_fatal().

void vlc_threads_setup

(

libvlc_int_t *

p_libvlc

)

References lock, rt_offset, rt_priorities, var_InheritBool, var_InheritInteger, vlc_mutex_lock(), vlc_mutex_unlock(), and VLC_STATIC_MUTEX.

int vlc_threadvar_create	(	vlc_threadvar_t *	key,
		void(*)(void *)	destr
	)

Allocates a thread-specific variable.

Parameters

key	where to store the thread-specific variable handle
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.

void vlc_threadvar_delete

(

vlc_threadvar_t *

p_tls

)

void* vlc_threadvar_get

(

vlc_threadvar_t

key

)

Gets 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.

int vlc_threadvar_set	(	vlc_threadvar_t	key,
		void *	value
	)

Sets a thread-specific variable.

Parameters

key	thread-local variable key (created with vlc_threadvar_create())
value	new value for the variable for the calling thread

Returns

0 on success, a system error code otherwise.

void vlc_trace	(	const char *	fn,
		const char *	file,
		unsigned	line
	)

Print a backtrace to the standard error for debugging purpose.

References fsync().

Referenced by vlc_thread_fatal().

Variable Documentation

int rt_offset

static

Referenced by vlc_clone_attr(), vlc_set_priority(), and vlc_threads_setup().

bool rt_priorities = false

static

Referenced by vlc_clone_attr(), vlc_set_priority(), and vlc_threads_setup().