bg.h File Reference

---

Detailed Description

Background task management.

Author:

Raphael Manfredi

Date:

2002-2003

#include <glib.h>

Go to the source code of this file.

Typedefs
typedef bgret_t(*	bgstep_cb_t )(gpointer h, gpointer ctx, gint ticks)
typedef void(*	bgsig_cb_t )(gpointer h, gpointer ctx, bgsig_t sig)
typedef void(*	bgclean_cb_t )(gpointer ctx)
typedef void(*	bgdone_cb_t )(gpointer h, gpointer ctx, bgstatus_t status, gpointer arg)
typedef void(*	bgstart_cb_t )(gpointer h, gpointer ctx, gpointer item)
typedef void(*	bgend_cb_t )(gpointer h, gpointer ctx, gpointer item)
typedef void(*	bgnotify_cb_t )(gpointer 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)
	bg_close
void	bg_sched_timer (void)
	bg_sched_timer
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_cancel (gpointer h)
	bg_task_cancel
void	bg_task_exit (gpointer h, gint code) G_GNUC_NORETURN
	bg_task_exit
void	bg_task_ticks_used (gpointer h, gint used)
	bg_task_ticks_used
bgsig_cb_t	bg_task_signal (gpointer h, bgsig_t sig, bgsig_cb_t handler)
	bg_task_signal
gint	bg_task_seqno (gpointer h)
gpointer	bg_task_context (gpointer h)

---

Typedef Documentation

typedef void(* bgclean_cb_t)(gpointer ctx)

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

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

typedef void(* bgnotify_cb_t)(gpointer h, gboolean on)

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

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

typedef bgret_t(* bgstep_cb_t)(gpointer 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   )

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_sched_timer (  void   )

bg_sched_timer Main task scheduling timer, called once per second.

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

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

---