bg.h File Reference

---

Detailed Description

Background task management.

Author:

Raphael Manfredi

Date:

2002-2003

#include "common.h"

Go to the source code of this file.

Typedefs
typedef bgret_t(*	bgstep_cb_t )(struct bgtask *h, gpointer ctx, gint ticks)
typedef void(*	bgsig_cb_t )(struct bgtask *h, gpointer ctx, bgsig_t sig)
typedef void(*	bgclean_cb_t )(gpointer ctx)
typedef void(*	bgdone_cb_t )(struct bgtask *h, gpointer ctx, bgstatus_t status, gpointer arg)
typedef void(*	bgstart_cb_t )(struct bgtask *h, gpointer ctx, gpointer item)
typedef void(*	bgend_cb_t )(struct bgtask *h, gpointer ctx, gpointer item)
typedef void(*	bgnotify_cb_t )(struct bgtask *h, gboolean on)
Enumerations
enum	bgret_t { BGR_NEXT = 0, BGR_MORE, BGR_DONE, BGR_ERROR }
	Return values for processing steps. More...
enum	bgstatus_t { BGS_OK = 0, BGS_ERROR, BGS_KILLED }
	Status codes for final "done" callback. More...
enum	bgsig_t {   BG_SIG_ZERO = 0, BG_SIG_KILL, BG_SIG_TERM, BG_SIG_USR,   BG_SIG_COUNT }
Functions
void	bg_close (void)
	Called at shutdown time.
void	bg_sched_timer (gboolean overloaded)
	Main task scheduling timer, called once per second.
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 *h, gpointer item)
	Enqueue work item to the daemon task.
void	bg_task_cancel (struct bgtask *h)
	Cancel a given task.
void	bg_task_exit (struct bgtask *h, gint code) G_GNUC_NORETURN
	Called by user code to "exit" the task.
void	bg_task_ticks_used (struct bgtask *h, 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.
bgsig_cb_t	bg_task_signal (struct bgtask *h, bgsig_t sig, bgsig_cb_t handler)
	Install user-level signal handler for a task signal.
gint	bg_task_seqno (const struct bgtask *h)
gpointer	bg_task_context (const struct bgtask *h)

---

Typedef Documentation

typedef void(* bgclean_cb_t)(gpointer ctx)

typedef void(* bgdone_cb_t)(struct bgtask *h, gpointer ctx, bgstatus_t status, gpointer arg)

typedef void(* bgend_cb_t)(struct bgtask *h, gpointer ctx, gpointer item)

typedef void(* bgnotify_cb_t)(struct bgtask *h, gboolean on)

typedef void(* bgsig_cb_t)(struct bgtask *h, gpointer ctx, bgsig_t sig)

typedef void(* bgstart_cb_t)(struct bgtask *h, gpointer ctx, gpointer item)

typedef bgret_t(* bgstep_cb_t)(struct bgtask *h, gpointer ctx, gint ticks)

---

Enumeration Type Documentation

enum bgret_t

Return values for processing steps. Enumeration values: BGR_NEXT  OK, move to next step. BGR_MORE  OK, still more work for this step. BGR_DONE  OK, end processing. BGR_ERROR  Error, abort processing.

enum bgsig_t

Enumeration values: BG_SIG_ZERO  No signal actually delivered. BG_SIG_KILL  Task is being killed (not trappable). BG_SIG_TERM  Task is being terminated. BG_SIG_USR  User-defined signal. BG_SIG_COUNT

enum bgstatus_t

Status codes for final "done" callback. Enumeration values: BGS_OK  OK, terminated normally. BGS_ERROR  Terminated with error. BGS_KILLED  Was killed by signal.

---

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_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_task_cancel (  struct bgtask *  h  )

Cancel a given task.

gpointer bg_task_context (  const struct bgtask *  h  )

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_exit (  struct bgtask *  bt, gint  code )

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

gint bg_task_seqno (  const struct bgtask *  h  )

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_ticks_used (  struct bgtask *  h, 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.

---