paraslash Paraslash Audio Streaming
About   News   Download   Documentation   Development

Enumerations | Functions | Variables
sched.c File Reference

Paraslash's scheduling functions. More...

#include <regex.h>
#include "para.h"
#include "ipc.h"
#include "fd.h"
#include "list.h"
#include "sched.h"
#include "string.h"
#include "time.h"
#include "error.h"

Enumerations

enum  task_status { TS_DEAD, TS_RUNNING }
 The possible states of a task. More...
 

Functions

int schedule (struct sched *s)
 The core function of all paraslash programs. More...
 
int task_reap (struct task **tptr)
 Obtain the error status of a task and deallocate its resources. More...
 
void sched_shutdown (struct sched *s)
 Deallocate all resources of all tasks of a scheduler instance. More...
 
struct task * task_register (struct task_info *info, struct sched *s)
 Add a task to the scheduler task list. More...
 
char * get_task_list (struct sched *s)
 Get the list of all registered tasks. More...
 
void task_notify (struct task *t, int err)
 Set the notification value of a task. More...
 
int task_get_notification (const struct task *t)
 Return the notification value of a task. More...
 
int task_status (const struct task *t)
 Return the status value of a task. More...
 
void task_notify_all (struct sched *s, int err)
 Set the notification value of all tasks of a scheduler instance. More...
 
void sched_min_delay (struct sched *s)
 Set the I/O timeout to the minimal possible value. More...
 
void sched_request_timeout (struct timeval *to, struct sched *s)
 Impose an upper bound for the I/O timeout. More...
 
void sched_request_timeout_ms (long unsigned ms, struct sched *s)
 Bound the I/O timeout to at most the given amount of milliseconds. More...
 
int sched_request_barrier (struct timeval *barrier, struct sched *s)
 Bound the I/O timeout by an absolute time in the future. More...
 
int sched_request_barrier_or_min_delay (struct timeval *barrier, struct sched *s)
 Bound the I/O timeout or request a minimal delay. More...
 
void sched_monitor_readfd (int fd, struct sched *s)
 Instruct the scheduler to monitor an fd for readiness for reading. More...
 
void sched_monitor_writefd (int fd, struct sched *s)
 Instruct the scheduler to monitor an fd for readiness for writing. More...
 
bool sched_read_ok (int fd, const struct sched *s)
 Check whether there is data to read on the given fd. More...
 
bool sched_write_ok (int fd, const struct sched *s)
 Check whether writing is possible (i.e., does not block). More...
 

Variables

const struct timeval * now = &now_struct
 This is set by the scheduler at the beginning of its main loop. More...
 

Detailed Description

Paraslash's scheduling functions.

Enumeration Type Documentation

◆ task_status

The possible states of a task.

In addition to the states listed here, a task may also enter zombie state. This happens when its ->post_monitor function returns negative, the ->status field is then set to this return value. Such tasks are not scheduled any more (i.e. ->pre_monitor() and ->post_monitor() are no longer called), but they stay on the scheduler task list until task_reap() or sched_shutdown() is called.

Enumerator
TS_DEAD 

Task has been reaped and may be removed from the task list.

TS_RUNNING 

Task is active.

Function Documentation

◆ schedule()

int schedule ( struct sched s)

The core function of all paraslash programs.

Parameters
sPointer to the scheduler struct.

This function updates the global now pointer, calls all registered pre_monitor hooks which may set the timeout and add any file descriptors to the pollfd array. Next, it calls the poll function and makes the result available to the registered tasks by calling their post_monitor hook.

Returns
Zero if no more tasks are left in the task list, negative if the poll function returned an error.
See also
now.

References clock_get_realtime(), sched::default_timeout, sched::num_pfds, sched::pidx, sched::pidx_array_len, sched::poll_function, sched::timeout, and xpoll().

◆ task_reap()

int task_reap ( struct task **  tptr)

Obtain the error status of a task and deallocate its resources.

Parameters
tptrIdentifies the task to reap.

This function is similar to wait(2) in that it returns information about a terminated task which allows releasing the resources associated with the task. Until this function is called, the terminated task remains in a zombie state.

Returns
If tptr is NULL, or *tptr is NULL, the function does nothing and returns zero. Otherwise, it is checked whether the task identified by tptr is still running. If it is, the function returns zero and again, no action is taken. Otherwise the (negative) error code of the terminated task is returned and *tptr is set to NULL. The task will then be removed removed from the scheduler task list.
See also
sched_shutdown(), wait(2).

References PARA_INFO_LOG, para_strerror(), and TS_DEAD.

◆ sched_shutdown()

void sched_shutdown ( struct sched s)

Deallocate all resources of all tasks of a scheduler instance.

Parameters
sThe scheduler instance.

This should only be called after schedule() has returned.

References list_for_each_entry_safe, PARA_WARNING_LOG, sched::task_list, and TS_RUNNING.

◆ task_register()

struct task* task_register ( struct task_info info,
struct sched s 
)

Add a task to the scheduler task list.

Parameters
infoTask information supplied by the caller.
sThe scheduler instance.
Returns
A pointer to a newly allocated task structure. It will be freed by sched_shutdown().

References alloc(), list_head::next, task_info::post_monitor, and sched::task_list.

Referenced by register_writer_node().

◆ get_task_list()

char* get_task_list ( struct sched s)

Get the list of all registered tasks.

Parameters
sThe scheduler instance to get the task list from.
Returns
The task list.

Each entry of the list contains an identifier which is simply a hex number. The result is dynamically allocated and must be freed by the caller.

References list_for_each_entry_safe, make_message(), sched::task_list, TS_DEAD, and TS_RUNNING.

Referenced by server_get_tasks().

◆ task_notify()

void task_notify ( struct task *  t,
int  err 
)

Set the notification value of a task.

Parameters
tThe task to notify.
errA positive error code.

Tasks which honor notifications are supposed to call task_get_notification() in their post_monitor function and act on the returned notification value.

If the scheduler detects during its pre_monitor loop that at least one task has been notified, the loop terminates, and the post_monitor methods of all taks are immediately called again.

The notification for a task is reset after the call to its post_monitor method.

See also
task_get_notification().

References PARA_INFO_LOG, and para_strerror().

Referenced by task_notify_all().

◆ task_get_notification()

int task_get_notification ( const struct task *  t)

Return the notification value of a task.

Parameters
tThe task to get the notification value from.
Returns
The notification value. If this is negative, the task has been notified by another task. Tasks are supposed to check for notifications by calling this function from their post_monitor method.
See also
task_notify().

◆ task_status()

int task_status ( const struct task *  t)

Return the status value of a task.

Parameters
tThe task to get the status value from.
Returns
Zero if task does not exist, one if task is running, negative error code if task has terminated.

References TS_DEAD, and TS_RUNNING.

◆ task_notify_all()

void task_notify_all ( struct sched s,
int  err 
)

Set the notification value of all tasks of a scheduler instance.

Parameters
sThe scheduler instance whose tasks should be notified.
errA positive error code.

This simply iterates over all existing tasks of s and sets each task's notification value to -err.

References list_for_each_entry, sched::task_list, and task_notify().

◆ sched_min_delay()

void sched_min_delay ( struct sched s)

Set the I/O timeout to the minimal possible value.

Parameters
sPointer to the scheduler struct.

This causes the next poll() call to return immediately.

References sched::timeout.

Referenced by check_wav_pre_monitor(), generic_filter_pre_monitor(), generic_recv_pre_monitor(), and sched_request_barrier_or_min_delay().

◆ sched_request_timeout()

void sched_request_timeout ( struct timeval *  to,
struct sched s 
)

Impose an upper bound for the I/O timeout.

Parameters
toMaximal allowed timeout.
sPointer to the scheduler struct.

If the current I/O timeout is already smaller than to, this function does nothing. Otherwise the timeout is set to the given value.

See also
sched_request_timeout_ms().

References sched::timeout, and tv2ms().

Referenced by sched_request_barrier(), sched_request_barrier_or_min_delay(), and sched_request_timeout_ms().

◆ sched_request_timeout_ms()

void sched_request_timeout_ms ( long unsigned  ms,
struct sched s 
)

Bound the I/O timeout to at most the given amount of milliseconds.

Parameters
msThe maximal allowed timeout in milliseconds.
sPointer to the scheduler struct.

Like sched_request_timeout() this imposes an upper bound on the I/O timeout.

References ms2tv(), and sched_request_timeout().

◆ sched_request_barrier()

int sched_request_barrier ( struct timeval *  barrier,
struct sched s 
)

Bound the I/O timeout by an absolute time in the future.

Parameters
barrierDefines the upper bound for the timeout.
sPointer to the scheduler struct.
Returns
If the barrier is in the past, this function does nothing and returns zero. Otherwise it returns one.
See also
sched_request_barrier_or_min_delay().

References now, sched_request_timeout(), and tv_diff().

◆ sched_request_barrier_or_min_delay()

int sched_request_barrier_or_min_delay ( struct timeval *  barrier,
struct sched s 
)

Bound the I/O timeout or request a minimal delay.

Parameters
barrierAbsolute time as in sched_request_barrier().
sPointer to the scheduler struct.
Returns
If the barrier is in the past, this function requests a minimal timeout and returns zero. Otherwise it returns one.
See also
sched_min_delay(), sched_request_barrier().

References now, sched_min_delay(), sched_request_timeout(), and tv_diff().

◆ sched_monitor_readfd()

void sched_monitor_readfd ( int  fd,
struct sched s 
)

Instruct the scheduler to monitor an fd for readiness for reading.

Parameters
fdThe file descriptor.
sThe scheduler.
See also
sched_monitor_writefd().

Referenced by signal_pre_monitor().

◆ sched_monitor_writefd()

void sched_monitor_writefd ( int  fd,
struct sched s 
)

Instruct the scheduler to monitor an fd for readiness for writing.

Parameters
fdThe file descriptor.
sThe scheduler.
See also
sched_monitor_readfd().

◆ sched_read_ok()

bool sched_read_ok ( int  fd,
const struct sched s 
)

Check whether there is data to read on the given fd.

To be called from the ->post_monitor() method of a task.

Parameters
fdShould have been monitored with sched_monitor_readfd().
sThe scheduler instance.
Returns
True if the file descriptor is ready for reading, false otherwise. If fd is negative, or has not been monitored in the current iteration of the scheduler's main loop, the function also returns false.
See also
sched_write_ok().

◆ sched_write_ok()

bool sched_write_ok ( int  fd,
const struct sched s 
)

Check whether writing is possible (i.e., does not block).

Parameters
fdShould have been monitored with sched_monitor_writefd().
sThe scheduler instance.
Returns
True if the file descriptor is ready for writing, false otherwise. The comment in sched_read_ok() about invalid file descriptors applies to this function as well.

Variable Documentation

◆ now

const struct timeval* now = &now_struct

This is set by the scheduler at the beginning of its main loop.

It may be used (read-only) from everywhere. As none of the functions called by the scheduler are allowed to block, this value should be accurate enough so that there is no need to call clock_gettime() directly.

Referenced by audiod_status_dump(), sched_request_barrier(), and sched_request_barrier_or_min_delay().