VLC  4.0.0-dev
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Threads and synchronization primitives
Collaboration diagram for Threads and synchronization primitives:

Modules

 Interruptible sleep
 
 Mutual exclusion locks
 
 Condition variables
 The condition variable is the most common and generic mean for threads to wait for events triggered by other threads.
 
 Semaphores
 The semaphore is the simplest thread synchronization primitive, consisting of a simple counter.
 
 Read/write locks
 Read/write locks are a type of thread synchronization primitive meant to protect access to data that is mostly read, and rarely written.
 
 Thread-specific variables
 
 Asynchronous/threaded timers
 

Files

file  vlc_threads.h
 Thread primitive declarations.
 

Data Structures

struct  vlc_thread_t
 Thread handle. More...
 
struct  vlc_once_t
 One-time initialization. More...
 

Macros

#define LIBVLC_USE_PTHREAD   1
 Whether LibVLC threads are based on POSIX threads. More...
 
#define LIBVLC_USE_PTHREAD_CLEANUP   1
 Whether LibVLC thread cancellation is based on POSIX threads. More...
 
#define VLC_THREAD_CANCELED   PTHREAD_CANCELED
 Return value of a canceled thread. More...
 
#define VLC_THREAD_PRIORITY_LOW   0
 
#define VLC_THREAD_PRIORITY_INPUT   0
 
#define VLC_THREAD_PRIORITY_AUDIO   0
 
#define VLC_THREAD_PRIORITY_VIDEO   0
 
#define VLC_THREAD_PRIORITY_OUTPUT   0
 
#define VLC_THREAD_PRIORITY_HIGHEST   0
 
#define VLC_STATIC_ONCE   { ATOMIC_VAR_INIT(0) }
 Static initializer for one-time initialization. More...
 
#define vlc_once(once, cb)   vlc_once_inline(once, cb)
 
#define VLC_HARD_MIN_SLEEP   VLC_TICK_FROM_MS(10) /* 10 milliseconds = 1 tick at 100Hz */
 
#define VLC_SOFT_MIN_SLEEP   VLC_TICK_FROM_SEC(9) /* 9 seconds */
 
#define check_delay(d)   (d)
 
#define check_deadline(d)   (d)
 
#define vlc_tick_sleep(d)   vlc_tick_sleep(check_delay(d))
 
#define vlc_tick_wait(d)   vlc_tick_wait(check_deadline(d))
 
#define vlc_cleanup_push(routine, arg)   pthread_cleanup_push (routine, arg)
 Registers a thread cancellation handler. More...
 
#define vlc_cleanup_pop()   pthread_cleanup_pop (0)
 Unregisters the last cancellation handler. More...
 
#define mutex_cleanup_push(lock)   vlc_cleanup_push (vlc_cleanup_lock, lock)
 
#define vlc_global_lock(n)   vlc_global_mutex(n, true)
 Acquires a global mutex. More...
 
#define vlc_global_unlock(n)   vlc_global_mutex(n, false)
 Releases a global mutex. More...
 

Typedefs

typedef struct vlc_cleanup_t vlc_cleanup_t
 

Enumerations

enum  {
  VLC_AVCODEC_MUTEX = 0 , VLC_GCRYPT_MUTEX , VLC_XLIB_MUTEX , VLC_MOSAIC_MUTEX ,
  VLC_MAX_MUTEX
}
 

Functions

void vlc_testcancel (void)
 Issues an explicit deferred cancellation point. More...
 
void vlc_once_inline (vlc_once_t *restrict once, void(*cb)(void))
 Executes a function one time. More...
 
int vlc_clone (vlc_thread_t *th, void *(*entry)(void *), void *data, int priority)
 Creates and starts a new thread. More...
 
void vlc_cancel (vlc_thread_t)
 Marks a thread as cancelled. More...
 
void vlc_join (vlc_thread_t th, void **result)
 Waits for a thread to complete (if needed), then destroys it. More...
 
int vlc_savecancel (void)
 Disables thread cancellation. More...
 
void vlc_restorecancel (int state)
 Restores the cancellation state. More...
 
void vlc_control_cancel (vlc_cleanup_t *)
 Internal handler for thread cancellation. More...
 
unsigned long vlc_thread_id (void)
 Thread identifier. More...
 
vlc_tick_t vlc_tick_now (void)
 Precision monotonic clock. More...
 
void vlc_tick_wait ((vlc_tick_t deadline))
 Waits until a deadline. More...
 
void vlc_tick_sleep ((vlc_tick_t delay))
 Waits for an interval of time. More...
 
unsigned vlc_GetCPUCount (void)
 Count CPUs. More...
 
static void vlc_cleanup_lock (void *lock)
 
void vlc_global_mutex (unsigned, bool)
 Internal handler for global mutexes. More...
 

Detailed Description

Macro Definition Documentation

◆ check_deadline

#define check_deadline (   d)    (d)

◆ check_delay

#define check_delay (   d)    (d)

◆ LIBVLC_USE_PTHREAD

#define LIBVLC_USE_PTHREAD   1

Whether LibVLC threads are based on POSIX threads.

◆ LIBVLC_USE_PTHREAD_CLEANUP

#define LIBVLC_USE_PTHREAD_CLEANUP   1

Whether LibVLC thread cancellation is based on POSIX threads.

◆ mutex_cleanup_push

#define mutex_cleanup_push (   lock)    vlc_cleanup_push (vlc_cleanup_lock, lock)

◆ vlc_cleanup_pop

#define vlc_cleanup_pop ( )    pthread_cleanup_pop (0)

Unregisters the last cancellation handler.

This pops the cancellation handler that was last pushed with vlc_cleanup_push() in the calling thread.

◆ vlc_cleanup_push

#define vlc_cleanup_push (   routine,
  arg 
)    pthread_cleanup_push (routine, arg)

Registers a thread cancellation handler.

This pushes a function to run if the thread is cancelled (or otherwise exits prematurely).

If multiple procedures are registered, they are handled in last-in first-out order.

Note
Any call to vlc_cleanup_push() must paired with a call to vlc_cleanup_pop().
Warning
Branching into or out of the block between these two function calls is not allowed (read: it will likely crash the whole process).
Parameters
routineprocedure to call if the thread ends
argargument for the procedure

◆ vlc_global_lock

#define vlc_global_lock (   n)    vlc_global_mutex(n, true)

Acquires a global mutex.

◆ vlc_global_unlock

#define vlc_global_unlock (   n)    vlc_global_mutex(n, false)

Releases a global mutex.

◆ VLC_HARD_MIN_SLEEP

#define VLC_HARD_MIN_SLEEP   VLC_TICK_FROM_MS(10) /* 10 milliseconds = 1 tick at 100Hz */

◆ vlc_once

#define vlc_once (   once,
  cb 
)    vlc_once_inline(once, cb)

◆ VLC_SOFT_MIN_SLEEP

#define VLC_SOFT_MIN_SLEEP   VLC_TICK_FROM_SEC(9) /* 9 seconds */

◆ VLC_STATIC_ONCE

#define VLC_STATIC_ONCE   { ATOMIC_VAR_INIT(0) }

Static initializer for one-time initialization.

◆ VLC_THREAD_CANCELED

#define VLC_THREAD_CANCELED   PTHREAD_CANCELED

Return value of a canceled thread.

◆ VLC_THREAD_PRIORITY_AUDIO

#define VLC_THREAD_PRIORITY_AUDIO   0

◆ VLC_THREAD_PRIORITY_HIGHEST

#define VLC_THREAD_PRIORITY_HIGHEST   0

◆ VLC_THREAD_PRIORITY_INPUT

#define VLC_THREAD_PRIORITY_INPUT   0

◆ VLC_THREAD_PRIORITY_LOW

#define VLC_THREAD_PRIORITY_LOW   0

◆ VLC_THREAD_PRIORITY_OUTPUT

#define VLC_THREAD_PRIORITY_OUTPUT   0

◆ VLC_THREAD_PRIORITY_VIDEO

#define VLC_THREAD_PRIORITY_VIDEO   0

◆ vlc_tick_sleep

#define vlc_tick_sleep (   d)    vlc_tick_sleep(check_delay(d))

◆ vlc_tick_wait

#define vlc_tick_wait (   d)    vlc_tick_wait(check_deadline(d))

Typedef Documentation

◆ vlc_cleanup_t

typedef struct vlc_cleanup_t vlc_cleanup_t

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
VLC_AVCODEC_MUTEX 
VLC_GCRYPT_MUTEX 
VLC_XLIB_MUTEX 
VLC_MOSAIC_MUTEX 
VLC_MAX_MUTEX 

Function Documentation

◆ vlc_cancel()

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 regardless of a thread being cancelled or not, to avoid leaking resources.

References vlc_thread_t::handle, vlc_atomic_notify_one(), and vlc_cancel_self().

Referenced by Close(), httpd_HostDelete(), vlc_getaddrinfo_i11e(), vlc_h2_conn_destroy(), and vlc_h2_output_destroy().

◆ vlc_cleanup_lock()

static void vlc_cleanup_lock ( void *  lock)
inlinestatic

References lock, and vlc_mutex_unlock().

◆ vlc_clone()

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

Creates and starts a new thread.

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

Parameters
thstorage space for the handle of the new thread (cannot be NULL) [OUT]
entryentry point for the thread
datadata parameter given to the entry point
prioritythread priority value
Returns
0 on success, a standard error code on error.
Note
In case of error, the value of *th is undefined.

References vlc_thread::cancel_event, vlc_thread::cancel_sock, vlc_thread::cleaners, vlc_thread::data, vlc_thread::done_event, vlc_thread::entry, vlc_thread::id, vlc_thread::killable, vlc_thread::killed, vlc_thread::tid, unlikely, vlc_clone_attr(), vlc_entry(), and VLC_THREAD_PRIORITY_HIGHEST.

Referenced by addons_manager_Gather(), decoder_New(), httpd_HostCreate(), input_Start(), InstallEntry(), OpenSDP(), OpenURL(), sout_AnnounceRegisterSDP(), SpawnThread(), spu_Create(), TsStart(), update_Check(), update_Download(), vlc_demux_chained_New(), vlc_getaddrinfo_i11e(), vlc_h2_output_create(), vlc_mta_acquire(), vlc_player_New(), vlc_timer_create(), vlm_New(), and vout_Request().

◆ vlc_control_cancel()

void vlc_control_cancel ( vlc_cleanup_t cleaner)

Internal handler for thread cancellation.

Do not call this function directly. Use wrapper macros instead: vlc_cleanup_push(), vlc_cleanup_pop().

References vlc_thread::cleaners, current_thread_ctx, and vlc_assert_unreachable.

◆ vlc_GetCPUCount()

unsigned vlc_GetCPUCount ( void  )

Count CPUs.

Returns
number of available (logical) CPUs.

References count, unlikely, and vlc_alloc().

◆ vlc_global_mutex()

void vlc_global_mutex ( unsigned  n,
bool  acquire 
)

Internal handler for global mutexes.

Do not use this function directly. Use helper macros instead: vlc_global_lock(), vlc_global_unlock().

References ARRAY_SIZE, lock, static_assert, VLC_MAX_MUTEX, vlc_mutex_lock(), vlc_mutex_unlock(), and VLC_STATIC_MUTEX.

◆ vlc_join()

void vlc_join ( vlc_thread_t  th,
void **  result 
)

Waits for a thread to complete (if needed), then destroys it.

Note
This is a cancellation point. In case of cancellation, the thread is not joined.
Warning
A thread cannot join itself (normally VLC will abort if this is attempted).
Parameters
ththread handle
result[OUT] pointer to write the thread return value or NULL

References vlc_thread_t::handle, vlc_testcancel(), VLC_THREAD_ASSERT, and vlc_WaitForSingleObject().

Referenced by addons_manager_Delete(), Close(), httpd_HostDelete(), input_Close(), spu_Destroy(), TsStop(), update_Check(), update_Delete(), update_Download(), vlc_demux_chained_Delete(), vlc_getaddrinfo_i11e(), vlc_h2_conn_destroy(), vlc_h2_output_destroy(), vlc_input_decoder_Delete(), vlc_mta_release(), vlc_player_Delete(), vlc_timer_destroy(), vlm_Delete(), and vout_StopDisplay().

◆ vlc_once_inline()

static void vlc_once_inline ( vlc_once_t *restrict  once,
void(*)(void)  cb 
)
inline

Executes a function one time.

The first time this function is called with a given one-time initialization object, it executes the provided callback. Any further call with the same object will be a no-op.

In the corner case that the first time execution is ongoing in another thread, then the function will wait for completion on the other thread (and then synchronize memory) before it returns. This ensures that, no matter what, the callback has been executed exactly once and its side effects are visible after the function returns.

Parameters
oncea one-time initialization object
cbcallback to execute (the first time)

References unlikely, and vlc_once.

◆ vlc_restorecancel()

void vlc_restorecancel ( int  state)

◆ vlc_savecancel()

int vlc_savecancel ( void  )

Disables thread cancellation.

This functions saves the current cancellation state (enabled or disabled), then disables cancellation for the calling thread. It 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.

Note
This function is not a cancellation point.
Returns
Previous cancellation state (opaque value for vlc_restorecancel()).

References current_thread_ctx, vlc_thread::killable, state, thread, and VLC_THREAD_ASSERT.

Referenced by FinderThread(), httpdLoop(), InstallerThread(), rtp_dgram_thread(), update_CheckReal(), update_DownloadReal(), vlc_h2_output_dequeue(), vlc_h2_recv_thread(), vlc_https_connect_proxy(), vlc_https_recv(), vlc_https_send(), vlc_mutex_lock(), vlc_object_deinit(), vlc_poll_i11e_inner(), vlc_poll_i11e_wake(), vlc_thread_fatal(), vlc_tls_ClientSessionCreate(), vlc_tls_ServerSessionCreate(), vlc_tls_SessionDelete(), and vlc_vaLogCallback().

◆ vlc_testcancel()

void vlc_testcancel ( void  )

Issues an explicit deferred cancellation point.

This has no effects 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 one (block_FifoGet() is an example).

References vlc_thread::cancel_event, vlc_thread::cleaners, current_thread_ctx, vlc_thread::data, vlc_thread::done_event, vlc_thread::killable, vlc_thread::killed, p, thread, vlc_cancel_self(), vlc_docancel(), VLC_THREAD_CANCELED, and vlc_thread_cleanup().

Referenced by block_FifoGet(), net_Read(), net_Write(), vlc_atomic_timedwait(), vlc_atomic_timedwait_daytime(), vlc_atomic_wait(), vlc_join(), vlc_poll_i11e_inner(), vlc_queue_Dequeue(), vlc_select(), and vlc_tick_wait().

◆ vlc_thread_id()

unsigned long vlc_thread_id ( void  )

Thread identifier.

This function returns a non-zero unique identifier of the calling thread. The identifier cannot change for the entire lifetime of the thread, and two concurrent threads cannot have the same identifier.

The thread identifier has no defined semantics other than uniqueness, and no particular purposes within LibVLC. It is provided mainly for tracing and debugging.

On some but not all supported platforms, the thread identifier is in fact the OS/kernel thread identifier (a.k.a. task PID), and is temporally unique not only within the process but across the entire system.

Note
The main() thread identifier is typically identical to the process identifier, but this is not portable.
Returns
the thread identifier (cannot fail)

References static_assert, and unlikely.

Referenced by vlc_mutex_held(), vlc_mutex_lock(), vlc_mutex_trylock(), vlc_thread_fatal(), vlc_thread_fatal_print(), and vlc_vaLog().

◆ vlc_tick_now()

vlc_tick_t vlc_tick_now ( 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 vlc_tick_wait() or vlc_tick_sleep(). 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 freq, lldiv(), mdate_selected, Q2LL, lldiv_t::quot, lldiv_t::rem, unlikely, vlc_tick_from_samples(), vlc_tick_from_sec, and vlc_tick_from_timespec.

Referenced by aout_DecDrain(), aout_DecPlay(), aout_DecSilence(), CmdInitAdd(), CmdInitControl(), CmdInitDel(), CmdInitPrivControl(), CmdInitSend(), Control(), DisplayPicture(), EsOutDecodersStopBuffering(), EsOutGetBuffering(), EsOutVaControlLocked(), httpdLoop(), ImageRead(), Init(), input_rate_Add(), input_thread_Events(), MainLoop(), net_Connect(), OSDWidget(), PreparePicture(), PrerenderPicture(), RenderPicture(), rtp_dequeue(), rtp_queue(), rtp_timeout(), RunnableRun(), RunThread(), sout_AnnounceRegisterSDP(), spu_PrerenderText(), spu_PutSubpicture(), Thread(), TsStart(), vlc_atomic_timedwait(), vlc_demux_chained_Thread(), vlc_input_decoder_AddVoutOverlay(), vlc_msleep_i11e(), vlc_player_input_GetPos(), vlc_player_input_GetTime(), vlc_player_WaitRetryDelay(), vlc_tick_sleep(), vlc_tick_wait(), vlc_timer_schedule(), vlc_timer_thread(), vlc_tls_ClientSessionCreate(), vout_chrono_Start(), vout_chrono_Stop(), vout_display_window_MouseEvent(), vout_OSDEpg(), vout_OSDText(), vout_SetInterlacingState(), vout_snapshot_Get(), and VoutSnapshotPip().

◆ vlc_tick_sleep()

void vlc_tick_sleep ( (vlc_tick_t delay)  )

Waits for an interval of time.

Parameters
delayhow long to wait (in microseconds)
Note
The delay may be exceeded due to OS scheduling.
This function is a cancellation point.

◆ vlc_tick_wait()

void vlc_tick_wait ( (vlc_tick_t deadline)  )

Waits until a deadline.

Parameters
deadlinetimestamp to wait for (vlc_tick_now())
Note
The deadline may be exceeded due to OS scheduling.
This function is a cancellation point.