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 "tm.h"
#include "walloc.h"
#include "override.h"

Data Structures
struct	bgtask
	Internal representation of a user-defined task. More...
Defines
#define	BT_MAGIC   0xbacc931dU /**< Internal bgtask magic number */
	Internal bgtask magic number.
#define	MAX_LIFE   150000 /**< In useconds, MUST be << 1 sec */
	In useconds, MUST be << 1 sec.
#define	MIN_LIFE   40000 /**< Min lifetime per task, in usecs */
	Min lifetime per task, in usecs.
#define	DELTA_FACTOR   4 /**< Max variations are 400% */
	Max variations are 400%.
#define	TASK_F_EXITED   0x00000001 /**< Exited */
	Exited.
#define	TASK_F_SIGNAL   0x00000002 /**< Signal received */
	Signal received.
#define	TASK_F_RUNNING   0x00000004 /**< Task is running */
	Task is running.
#define	TASK_F_ZOMBIE   0x00000008 /**< Task waiting status collect */
	Task waiting status collect.
#define	TASK_F_NOTICK   0x00000010 /**< Do no recompute tick info */
	Do no recompute tick info.
#define	TASK_F_SLEEPING   0x00000020 /**< Task is sleeping */
	Task is sleeping.
#define	TASK_F_RUNNABLE   0x00000040 /**< Task is runnable */
	Task is runnable.
#define	TASK_F_DAEMON   0x80000000 /**< Task is a daemon */
	Task is a daemon.
#define	TASK(x)   ((struct bgtask *) (x))
Functions
	RCSID ("$Id:bg.c, v 1.9 2005/08/31 21:37:32 rmanfredi Exp $")
gint	bg_task_seqno (gpointer h)
gpointer	bg_task_context (gpointer h)
void	bg_sched_add (struct bgtask *bt)
	bg_sched_add
void	bg_sched_remove (struct bgtask *bt)
	bg_sched_remove
bgtask *	bg_sched_pick (void)
	bg_sched_pick
void	bg_task_suspend (struct bgtask *bt)
	bg_task_suspend
void	bg_task_resume (struct bgtask *bt)
	bg_task_resume
void	bg_sched_sleep (struct bgtask *bt)
	bg_sched_sleep
void	bg_sched_wakeup (struct bgtask *bt)
	bg_sched_wakeup
bgtask *	bg_task_switch (struct bgtask *bt)
	bg_task_switch
gpointer	bg_task_create (gchar *name, bgstep_cb_t *steps, gint stepcnt, gpointer ucontext, bgclean_cb_t ucontext_free, bgdone_cb_t done_cb, gpointer done_arg)
	Callback argument.
gpointer	bg_daemon_create (gchar *name, 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)
	Start/Stop notify (optional).
void	bg_daemon_enqueue (gpointer h, gpointer item)
	bg_daemon_enqueue
void	bg_task_free (struct bgtask *bt)
	bg_task_free
void	bg_task_terminate (struct bgtask *bt)
	bg_task_terminate
void	bg_task_exit (gpointer h, gint code)
	bg_task_exit
void	bg_task_sendsig (struct bgtask *bt, bgsig_t sig, bgsig_cb_t handler)
	bg_task_sendsig
gint	bg_task_kill (gpointer h, bgsig_t sig)
	bg_task_kill
bgsig_cb_t	bg_task_signal (gpointer h, bgsig_t sig, bgsig_cb_t handler)
	bg_task_signal
void	bg_task_deliver_signals (struct bgtask *bt)
	bg_task_deliver_signals
void	bg_task_cancel (gpointer h)
	bg_task_cancel
void	bg_task_ticks_used (gpointer h, gint used)
	bg_task_ticks_used
void	bg_reclaim_dead (void)
	bg_reclaim_dead
void	bg_task_ended (struct bgtask *bt)
	bg_task_ended
void	bg_sched_timer (void)
	bg_sched_timer
void	bg_close (void)
	bg_close
Variables
guint32	common_dbg = 0
GSList *	runq = NULL
GSList *	sleepq = NULL
gint	runcount = 0
GSList *	dead_tasks = NULL
bgtask *	current_task = NULL

---

Define Documentation

#define BT_MAGIC   0xbacc931dU /**< Internal bgtask magic number */

Internal bgtask magic number.

#define DELTA_FACTOR   4 /**< Max variations are 400% */

Max variations are 400%.

#define MAX_LIFE   150000 /**< In useconds, MUST be << 1 sec */

In useconds, MUST be << 1 sec.

#define MIN_LIFE   40000 /**< Min lifetime per task, in usecs */

Min lifetime per task, in usecs.

#define TASK (  x   )     ((struct bgtask *) (x))

#define TASK_F_DAEMON   0x80000000 /**< Task is a daemon */

Task is a daemon.

#define TASK_F_EXITED   0x00000001 /**< Exited */

Exited.

#define TASK_F_NOTICK   0x00000010 /**< Do no recompute tick info */

Do no recompute tick info.

#define TASK_F_RUNNABLE   0x00000040 /**< Task is runnable */

Task is runnable.

#define TASK_F_RUNNING   0x00000004 /**< Task is running */

Task is running.

#define TASK_F_SIGNAL   0x00000002 /**< Signal received */

Signal received.

#define TASK_F_SLEEPING   0x00000020 /**< Task is sleeping */

Task is sleeping.

#define TASK_F_ZOMBIE   0x00000008 /**< Task waiting status collect */

Task waiting status collect.

---

Function Documentation

void bg_close (  void   )

bg_close Called at shutdown time.

gpointer bg_daemon_create (  gchar *  name, 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 )

Start/Stop notify (optional). 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) stepcnt  Work to perform (copied) 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 (  gpointer  h, gpointer  item )

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

void bg_reclaim_dead (  void   )  [static]

bg_reclaim_dead Reclaim all dead tasks

void bg_sched_add (  struct bgtask *  bt  )  [static]

bg_sched_add Add new task to the scheduler (run queue).

struct bgtask* bg_sched_pick (  void   )  [static]

bg_sched_pick Pick next task to schedule.

void bg_sched_remove (  struct bgtask *  bt  )  [static]

bg_sched_remove Remove task from the scheduler (run queue).

void bg_sched_sleep (  struct bgtask *  bt  )  [static]

bg_sched_sleep Add task to the sleep queue.

void bg_sched_timer (  void   )

bg_sched_timer Main task scheduling timer, called once per second.

void bg_sched_wakeup (  struct bgtask *  bt  )  [static]

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

void bg_task_cancel (  gpointer  h  )

bg_task_cancel Cancel a given task.

gpointer bg_task_context (  gpointer  h  )

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

Callback argument. 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) stepcnt  Work to perform (copied) 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]

bg_task_deliver_signals Deliver all the signals queued so far for the task.

void bg_task_ended (  struct bgtask *  bt  )  [static]

bg_task_ended Called when a task has ended its processing.

void bg_task_exit (  gpointer  h, gint  code )

bg_task_exit 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]

bg_task_free Free task structure.

gint bg_task_kill (  gpointer  h, bgsig_t  sig )  [static]

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

void bg_task_resume (  struct bgtask *  bt  )  [static]

bg_task_resume Resume task execution.

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

bg_task_sendsig Deliver signal via the user's signal handler.

gint bg_task_seqno (  gpointer  h  )

bgsig_cb_t bg_task_signal (  gpointer  h, bgsig_t  sig, bgsig_cb_t  handler )

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

void bg_task_suspend (  struct bgtask *  bt  )  [static]

bg_task_suspend Suspend task.

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

bg_task_switch 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]

bg_task_terminate Terminate the task, invoking the completion callback if defined.

void bg_task_ticks_used (  gpointer  h, gint  used )

bg_task_ticks_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.

RCSID (  "$Id:bg.  c, v 1.9 2005/08/31 21:37:32 rmanfredi Exp $"  )

---

Variable Documentation

guint32 common_dbg = 0 [static]

struct bgtask* current_task = NULL [static]

GSList* dead_tasks = NULL [static]

gint runcount = 0 [static]

GSList* runq = NULL [static]

GSList* sleepq = NULL [static]

---