vlc_executor.h File Reference

Include dependency graph for vlc_executor.h:

Go to the source code of this file.

Data Structures
struct	vlc_runnable
	A Runnable encapsulates a task to be run from an executor thread. More...

Typedefs
typedef struct vlc_executor	vlc_executor_t
	Executor type (opaque)

Functions
vlc_executor_t *	vlc_executor_New (unsigned max_threads)
	Create a new executor.
void	vlc_executor_Delete (vlc_executor_t *executor)
	Delete an executor.
void	vlc_executor_Submit (vlc_executor_t *executor, struct vlc_runnable *runnable)
	Submit a runnable for execution.
bool	vlc_executor_Cancel (vlc_executor_t *executor, struct vlc_runnable *runnable)
	Cancel a runnable previously submitted.
void	vlc_executor_WaitIdle (vlc_executor_t *executor)
	Wait until all submitted tasks are completed or canceled.

Typedef Documentation

vlc_executor_t

typedef struct vlc_executor vlc_executor_t

Executor type (opaque)

Function Documentation

vlc_executor_Cancel()

bool vlc_executor_Cancel	(	vlc_executor_t *	executor,
		struct vlc_runnable *	runnable
	)

Cancel a runnable previously submitted.

If this runnable is still queued (i.e. it has not be run yet), then dequeue it so that it will never be run, and return true.

Otherwise, this runnable has already been taken by an executor thread (it is still running or is complete). In that case, do nothing, and return false.

This is an error to pass a runnable not submitted to this executor (the result is undefined in that case).

Note that the runnable instance is owned by the caller, so the executor will never attempt to free it.

Parameters

executor	the executor
runnable	the task to cancel

Return values

true	if the runnable has been canceled before execution
false	if the runnable has not been canceled

References vlc_executor::idle_wait, vlc_executor::lock, vlc_list::next, vlc_runnable::node, vlc_list::prev, vlc_executor::unfinished, vlc_cond_signal(), vlc_list_remove(), vlc_mutex_lock(), and vlc_mutex_unlock().

Referenced by CancelAllTasks(), and vlc_preparser_Cancel().

vlc_executor_Delete()

void vlc_executor_Delete

(

vlc_executor_t *

executor

)

Delete an executor.

Wait for all the threads to complete, and delete the executor instance.

All submitted tasks must be either started or explicitly canceled. To wait for all tasks to complete, use vlc_executor_WaitIdle().

It is an error to submit a new runnable after vlc_executor_Delete() is called. In particular, a running task must not submit a new runnable once deletion has been requested.

Parameters

executor

the executor

References vlc_executor::closing, vlc_executor::lock, vlc_executor_thread::node, vlc_executor::queue, vlc_executor::queue_wait, vlc_thread::thread, thread, vlc_executor::threads, vlc_executor::unfinished, vlc_cond_broadcast(), vlc_join(), vlc_list_foreach, vlc_list_is_empty(), vlc_mutex_lock(), and vlc_mutex_unlock().

Referenced by input_fetcher_Delete(), input_fetcher_New(), vlc_preparser_Delete(), and vlc_preparser_New().

vlc_executor_New()

vlc_executor_t * vlc_executor_New

(

unsigned

max_threads

)

Create a new executor.

Parameters

max_threads

the maximum number of threads used to execute runnables

Returns

a pointer to a new executor, or NULL if an error occurred

References vlc_executor::closing, vlc_executor::idle_wait, vlc_executor::lock, vlc_executor::max_threads, vlc_executor::nthreads, vlc_executor::queue, vlc_executor::queue_wait, SpawnThread(), vlc_executor::threads, vlc_executor::unfinished, vlc_cond_init(), vlc_list_init(), vlc_mutex_init(), and VLC_SUCCESS.

Referenced by input_fetcher_New(), and vlc_preparser_New().

vlc_executor_Submit()

void vlc_executor_Submit	(	vlc_executor_t *	executor,
		struct vlc_runnable *	runnable
	)

Submit a runnable for execution.

The struct vlc_runnable is not copied, it must exist until the end of the execution (the user is expected to embed it in its own task structure).

Here is a simple example:

struct my_task {
    char *str;
    struct vlc_runnable runnable;
};
 
static void Run(void *userdata)
{
    struct my_task *task = userdata;
 
    printf("start of %s\n", task->str);
    vlc_tick_sleep(VLC_TICK_FROM_SEC(3)); // long action
    printf("end of %s\n", task->str);
 
    free(task->str);
    free(task);
}
 
void foo(vlc_executor_t *executor, const char *str)
{
    // no error handling for brevity
    struct my_task *task = malloc(sizeof(*task));
    task->str = strdup(str);
    task->runnable.run = Run;
    task->runnable.userdata = task;
    vlc_executor_Submit(executor, &task->runnable);
}

A runnable instance is intended to be submitted at most once. The caller is expected to allocate a new task structure (embedding the runnable) for every submission.

More precisely, it is incorrect to submit a runnable already submitted that is still in the pending queue (i.e. not canceled or started). This is due to the intrusive linked list of runnables.

It is strongly discouraged to submit a runnable that is currently running on the executor (unless you are prepared for the run() callback to be run several times in parallel).

For simplicity, it is discouraged to submit a runnable previously submitted.

Parameters

executor	the executor
runnable	the task to run

References vlc_executor::closing, vlc_executor::lock, vlc_executor::max_threads, vlc_executor::nthreads, QueuePush(), SpawnThread(), vlc_executor::unfinished, vlc_mutex_lock(), and vlc_mutex_unlock().

Referenced by Submit(), vlc_preparser_GenerateThumbnail(), and vlc_preparser_Push().

vlc_executor_WaitIdle()

void vlc_executor_WaitIdle

(

vlc_executor_t *

executor

)

Wait until all submitted tasks are completed or canceled.

Parameters

executor

the executor

References vlc_executor::idle_wait, vlc_executor::lock, vlc_executor::unfinished, vlc_cond_wait(), vlc_mutex_lock(), and vlc_mutex_unlock().