bg.c File Reference

---

Detailed Description

Background task management.

A background task is some CPU or I/O intensive operation that needs to be split up in small chunks of processing because it would block the process for too long if executed atomically.

Author:

Raphael Manfredi

Date:

2002-2003

#include "common.h"
#include "bg.h"
#include "misc.h"
#include "tm.h"
#include "walloc.h"
#include "override.h"

Data Structures
struct	bgtask
	Internal representation of a user-defined task. More...
Defines
#define	MAX_LIFE   350000
	In useconds, MUST be << 1 sec.
#define	MIN_LIFE   40000
	Min lifetime per task, in usecs.
#define	DELTA_FACTOR   4
	Max variations are 400%.
Enumerations
enum	bgtask_magic { BGTASK_MAGIC = 0xbacc931dU, BGTASK_DEAD_MAGIC = 0x6f5c8a03U }
enum	{   TASK_F_EXITED = 1 << 0, TASK_F_SIGNAL = 1 << 1, TASK_F_RUNNING = 1 << 2, TASK_F_ZOMBIE = 1 << 3,   TASK_F_NOTICK = 1 << 4, TASK_F_SLEEPING = 1 << 5, TASK_F_RUNNABLE = 1 << 6, TASK_F_DAEMON = 1 << 7 }
Functions
void	bg_task_check (const struct bgtask *const bt)
gint	bg_task_seqno (const struct bgtask *bt)
gpointer	bg_task_context (const struct bgtask *bt)
void	bg_sched_add (struct bgtask *bt)
	Add new task to the scheduler (run queue).
void	bg_sched_remove (struct bgtask *bt)
	Remove task from the scheduler (run queue).
bgtask *	bg_sched_pick (void)
	Pick next task to schedule.
void	bg_task_suspend (struct bgtask *bt)
	Suspend task.
void	bg_task_resume (struct bgtask *bt)
	Resume task execution.
void	bg_sched_sleep (struct bgtask *bt)
	Add task to the sleep queue.
void	bg_sched_wakeup (struct bgtask *bt)
	Remove task from the sleep queue and insert it to the runqueue.
bgtask *	bg_task_switch (struct bgtask *bt)
	Switch to new task `bt'.
bgtask *	bg_task_alloc (void)
bgtask *	bg_task_create (const gchar *name, const bgstep_cb_t *steps, gint stepcnt, gpointer ucontext, bgclean_cb_t ucontext_free, bgdone_cb_t done_cb, gpointer done_arg)
	Create a new background task.
bgtask *	bg_daemon_create (const gchar *name, const bgstep_cb_t *steps, gint stepcnt, gpointer ucontext, bgclean_cb_t ucontext_free, bgstart_cb_t start_cb, bgend_cb_t end_cb, bgclean_cb_t item_free, bgnotify_cb_t notify)
	A "daemon" is a task equipped with a work queue.
void	bg_daemon_enqueue (struct bgtask *bt, gpointer item)
	Enqueue work item to the daemon task.
void	bg_task_free (struct bgtask *bt)
	Free task structure.
void	bg_task_terminate (struct bgtask *bt)
	Terminate the task, invoking the completion callback if defined.
void	bg_task_exit (struct bgtask *bt, gint code)
	Called by user code to "exit" the task.
void	bg_task_sendsig (struct bgtask *bt, bgsig_t sig, bgsig_cb_t handler)
	Deliver signal via the user's signal handler.
gint	bg_task_kill (struct bgtask *bt, bgsig_t sig)
	Send a signal to the given task.
bgsig_cb_t	bg_task_signal (struct bgtask *bt, bgsig_t sig, bgsig_cb_t handler)
	Install user-level signal handler for a task signal.
void	bg_task_deliver_signals (struct bgtask *bt)
	Deliver all the signals queued so far for the task.
void	bg_task_cancel (struct bgtask *bt)
	Cancel a given task.
void	bg_task_ticks_used (struct bgtask *bt, gint used)
	This routine can be called by the task when a single step is not using all its ticks and it matters for the computation of the cost per tick.
void	bg_reclaim_dead (void)
	Reclaim all dead tasks.
void	bg_task_ended (struct bgtask *bt)
	Called when a task has ended its processing.
void	bg_sched_timer (gboolean overloaded)
	Main task scheduling timer, called once per second.
guint	bg_task_terminate_all (GSList **ptr)
void	bg_close (void)
	Called at shutdown time.
Variables
guint32	common_dbg = 0
gint	runcount
GSList *	runq
GSList *	sleepq
GSList *	dead_tasks
bgtask *	current_task

---

Define Documentation

#define DELTA_FACTOR   4

Max variations are 400%.

#define MAX_LIFE   350000

In useconds, MUST be << 1 sec.

#define MIN_LIFE   40000

Min lifetime per task, in usecs.

---

Enumeration Type Documentation

anonymous enum

Enumeration values: TASK_F_EXITED  Exited. TASK_F_SIGNAL  Signal received. TASK_F_RUNNING  Task is running. TASK_F_ZOMBIE  Task waiting status collect. TASK_F_NOTICK  Do no recompute tick info. TASK_F_SLEEPING  Task is sleeping. TASK_F_RUNNABLE  Task is runnable. TASK_F_DAEMON  Task is a daemon.

enum bgtask_magic

Enumeration values: BGTASK_MAGIC  BGTASK_DEAD_MAGIC

---

Function Documentation

void bg_close (  void   )

Called at shutdown time.

struct bgtask* bg_daemon_create (  const gchar *  name, const bgstep_cb_t *  steps, gint  stepcnt, gpointer  ucontext, bgclean_cb_t  ucontext_free, bgstart_cb_t  start_cb, bgend_cb_t  end_cb, bgclean_cb_t  item_free, bgnotify_cb_t  notify )

A "daemon" is a task equipped with a work queue. When the daemon is initially created, it has an empty work queue and it is put in the "sleeping" state where it is not scheduled. As long as there is work in the work queue, the task is scheduled. It goes back to sleep when the work queue becomes empty. The `steps' given represent the processing to be done on each item of the work queue. The `start_cb' callback is invoked before working on a new item, so that the context can be initialized. The `end+cb' callback is invoked when the item has been processed (successfully or not). Since a daemon is not supposed to exit (although it can), there is no `done' callback. Use bg_daemon_enqueue() to enqueue more work to the daemon. Parameters: name  Task name (for tracing) steps  Work to perform (copied) stepcnt  Number of steps ucontext  User context ucontext_free  Free routine for context start_cb  Starting working on an item end_cb  Done working on an item item_free  Free routine for work queue items notify  Start/Stop notify (optional)

void bg_daemon_enqueue (  struct bgtask *  bt, gpointer  item )

Enqueue work item to the daemon task. If task was sleeping, wake it up.

void bg_reclaim_dead (  void   )  [static]

Reclaim all dead tasks.

void bg_sched_add (  struct bgtask *  bt  )  [static]

Add new task to the scheduler (run queue).

struct bgtask* bg_sched_pick (  void   )  [static]

Pick next task to schedule.

void bg_sched_remove (  struct bgtask *  bt  )  [static]

Remove task from the scheduler (run queue).

void bg_sched_sleep (  struct bgtask *  bt  )  [static]

Add task to the sleep queue.

void bg_sched_timer (  gboolean  overloaded  )

Main task scheduling timer, called once per second. Parameters: overloaded  when TRUE, CPU is already deemed to be busy enough

void bg_sched_wakeup (  struct bgtask *  bt  )  [static]

Remove task from the sleep queue and insert it to the runqueue.

struct bgtask* bg_task_alloc (  void   )  [static]

void bg_task_cancel (  struct bgtask *  bt  )

Cancel a given task.

void bg_task_check (  const struct bgtask *const   bt  )  [inline, static]

gpointer bg_task_context (  const struct bgtask *  bt  )

struct bgtask* bg_task_create (  const gchar *  name, const bgstep_cb_t *  steps, gint  stepcnt, gpointer  ucontext, bgclean_cb_t  ucontext_free, bgdone_cb_t  done_cb, gpointer  done_arg )

Create a new background task. The `steps' array is cloned, so it can be built on the caller's stack. Each time the task is scheduled, the current processing step is ran. Each step should perform a small amount of work, as determined by the number of ticks it is allowed to process. When a step is done, we move to the next step. When the task is done, the `done_cb' callback is called, if supplied. The user-supplied argument `done_arg' will also be given to that callback. Note that "done" does not necessarily mean success. Returns: an opaque handle. Parameters: name  Task name (for tracing) steps  Work to perform (copied) stepcnt  Number of steps ucontext  User context ucontext_free  Free routine for context done_cb  Notification callback when done done_arg  Callback argument

void bg_task_deliver_signals (  struct bgtask *  bt  )  [static]

Deliver all the signals queued so far for the task.

void bg_task_ended (  struct bgtask *  bt  )  [static]

Called when a task has ended its processing.

void bg_task_exit (  struct bgtask *  bt, gint  code )

Called by user code to "exit" the task. We exit immediately, not returning to the user code.

void bg_task_free (  struct bgtask *  bt  )  [static]

Free task structure.

gint bg_task_kill (  struct bgtask *  bt, bgsig_t  sig )  [static]

Send a signal to the given task. Returns: -1 if the task could not be signalled.

void bg_task_resume (  struct bgtask *  bt  )  [static]

Resume task execution.

void bg_task_sendsig (  struct bgtask *  bt, bgsig_t  sig, bgsig_cb_t  handler )  [static]

Deliver signal via the user's signal handler.

gint bg_task_seqno (  const struct bgtask *  bt  )

bgsig_cb_t bg_task_signal (  struct bgtask *  bt, bgsig_t  sig, bgsig_cb_t  handler )

Install user-level signal handler for a task signal. Returns: previously installed signal handler.

void bg_task_suspend (  struct bgtask *  bt  )  [static]

Suspend task.

struct bgtask* bg_task_switch (  struct bgtask *  bt  )  [static]

Switch to new task `bt'. If argument is NULL, suspends current task. Returns: previously scheduled task, if any.

void bg_task_terminate (  struct bgtask *  bt  )  [static]

Terminate the task, invoking the completion callback if defined.

guint bg_task_terminate_all (  GSList **  ptr  )  [static]

void bg_task_ticks_used (  struct bgtask *  bt, gint  used )

This routine can be called by the task when a single step is not using all its ticks and it matters for the computation of the cost per tick.

---

Variable Documentation

guint32 common_dbg = 0 [static]

struct bgtask* current_task [static]

GSList* dead_tasks [static]

gint runcount [static]

GSList* runq [static]

GSList* sleepq [static]

---