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

enum 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

s	Pointer 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

tptr	Identifies 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

s	The 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

info	Task information supplied by the caller.
s	The 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

s	The 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

t	The task to notify.
err	A 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

t	The 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

t	The 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

s	The scheduler instance whose tasks should be notified.
err	A 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

s	Pointer 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

to	Maximal allowed timeout.
s	Pointer 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

ms	The maximal allowed timeout in milliseconds.
s	Pointer 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

barrier	Defines the upper bound for the timeout.
s	Pointer 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

barrier	Absolute time as in sched_request_barrier().
s	Pointer 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

fd	The file descriptor.
s	The 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

fd	The file descriptor.
s	The 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

fd	Should have been monitored with sched_monitor_readfd().
s	The 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

fd	Should have been monitored with sched_monitor_writefd().
s	The 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().