Data Structures
struct	_CairoDockTask
	Definition of a periodic and asynchronous Task. More...
Defines
#define	cairo_dock_new_task(iPeriod, get_data, update, pSharedMemory)
#define	cairo_dock_get_task_elapsed_time(pTask)
Typedefs
typedef void(*	CairoDockGetDataAsyncFunc )(gpointer pSharedMemory)
	Definition of the asynchronous job, that does the heavy part.
typedef gboolean(*	CairoDockUpdateSyncFunc )(gpointer pSharedMemory)
	Definition of the synchronous job, that update the dock with the results of the previous job. Returns TRUE to continue, FALSE to stop.
Enumerations
enum	CairoDockFrequencyState
	Type of frequency for a periodic task. The frequency of the Task is divided by 2, 4, and 10 for each state.
Functions
void	cairo_dock_launch_task (CairoDockTask *pTask)
void	cairo_dock_launch_task_delayed (CairoDockTask *pTask, double fDelay)
CairoDockTask *	cairo_dock_new_task_full (int iPeriod, CairoDockGetDataAsyncFunc get_data, CairoDockUpdateSyncFunc update, GFreeFunc free_data, gpointer pSharedMemory)
void	cairo_dock_stop_task (CairoDockTask *pTask)
void	cairo_dock_discard_task (CairoDockTask *pTask)
void	cairo_dock_free_task (CairoDockTask *pTask)
gboolean	cairo_dock_task_is_active (CairoDockTask *pTask)
gboolean	cairo_dock_task_is_running (CairoDockTask *pTask)
void	cairo_dock_change_task_frequency (CairoDockTask *pTask, int iNewPeriod)
void	cairo_dock_relaunch_task_immediately (CairoDockTask *pTask, int iNewPeriod)
void	cairo_dock_downgrade_task_frequency (CairoDockTask *pTask)
void	cairo_dock_set_normal_task_frequency (CairoDockTask *pTask)

Detailed Description

An easy way to define periodic and asynchronous tasks, that can perform heavy jobs without blocking the dock.

A Task is divided in 2 phases :

the asynchronous phase will be executed in another thread, while the dock continues to run on its own thread, in parallel. During this phase you will do all the heavy job (like downloading a file or computing something) but you can't interact on the dock.
the synchronous phase will be executed after the first one has finished. There you will update your applet with the result of the first phase.

Attention:: A data buffer is used to communicate between the 2 phases. It is important that these datas are never accessed outside the task, and vice versa that the asynchronous thread never accesses other data than this buffer.
If you want to access these datas outside the task, you have to copy them in a safe place during the 2nd phase, or to stop the task before (beware that stopping the task means waiting for the 1st phase to finish, which can take some time).

You create a Task with cairo_dock_new_task, launch it with cairo_dock_launch_task, and destroy it with cairo_dock_free_task.

A Task can be periodic if you specify a period, otherwise it will be executed once. It also can also be fully synchronous if you don't specify an asynchronous function.

Define Documentation

#define cairo_dock_new_task	(	iPeriod,
		get_data,
		update,
		pSharedMemory
	)

Create a periodic Task.

Parameters:

iPeriod	time between 2 iterations, possibly nul for a Task to be executed once only.
get_data	asynchonous function, which carries out the heavy job parallel to the dock; stores the results in the shared memory.
update	synchonous function, which carries out the update of the dock from the result of the previous function. Returns TRUE to continue, FALSE to stop.
pSharedMemory	structure passed as a parameter of the get_data and update functions. Must not be accessed outside of these functions !

Returns:: the newly allocated Task, ready to be launched with cairo_dock_launch_task. Free it with cairo_dock_free_task.

#define cairo_dock_get_task_elapsed_time ( pTask )

Get the time elapsed since the last time the Task has run.

Parameters:

pTask the periodic Task.

Function Documentation

void cairo_dock_launch_task ( CairoDockTask * pTask )

Launch a periodic Task, beforehand prepared with cairo_dock_new_task. The first iteration is executed immediately. The frequency returns to its normal state.

Parameters:

pTask the periodic Task.

void cairo_dock_launch_task_delayed	(	CairoDockTask *	pTask,
		double	fDelay
	)

Same as above but after a delay.

Parameters:

pTask	the periodic Task.
fDelay	delay in ms.

CairoDockTask* cairo_dock_new_task_full	(	int	iPeriod,
		CairoDockGetDataAsyncFunc	get_data,
		CairoDockUpdateSyncFunc	update,
		GFreeFunc	free_data,
		gpointer	pSharedMemory
	)

Create a periodic Task.

Parameters:

iPeriod	time between 2 iterations, possibly nul for a Task to be executed once only.
get_data	asynchonous function, which carries out the heavy job parallel to the dock; stores the results in the shared memory.
update	synchonous function, which carries out the update of the dock from the result of the previous function. Returns TRUE to continue, FALSE to stop.
free_data	function called when the Task is destroyed, to free the shared memory (optionnal).
pSharedMemory	structure passed as a parameter of the get_data and update functions. Must not be accessed outside of these functions !

Returns:: the newly allocated Task, ready to be launched with cairo_dock_launch_task. Free it with cairo_dock_free_task.

void cairo_dock_stop_task ( CairoDockTask * pTask )

Stop a periodic Task. If the Task is running, it will wait until the asynchronous thread has finished, and skip the update. The Task can be launched again with a call to cairo_dock_launch_task.

Parameters:

pTask the periodic Task.

void cairo_dock_discard_task ( CairoDockTask * pTask )

Discard a periodic Task. The asynchronous thread will continue, and the Task will be freed when it ends. Use this function carefully, since you don't know when the free will occur (especially if you've set a free_data callback). The Task should be considered as destroyed after a call to this function.

Parameters:

pTask the periodic Task.

void cairo_dock_free_task ( CairoDockTask * pTask )

Stop and destroy a periodic Task, freeing all the allocated ressources. Unlike cairo_dock_discard_task, the task is stopped before being freeed, so this is a blocking call. If you want to destroy the task inside the update callback, don't use this function; use cairo_dock_discard_task instead.

Parameters:

pTask the periodic Task.

gboolean cairo_dock_task_is_active ( CairoDockTask * pTask )

Tell if a Task is active, that is to say is periodically called.

Parameters:

pTask the periodic Task.

Returns:: TRUE if the Task is active.

gboolean cairo_dock_task_is_running ( CairoDockTask * pTask )

Tell if a Task is running, that is to say it is either in the thread or waiting for the update.

Parameters:

pTask the periodic Task.

Returns:: TRUE if the Task is running.

void cairo_dock_change_task_frequency	(	CairoDockTask *	pTask,
		int	iNewPeriod
	)

Change the frequency of a Task. The next iteration is re-scheduled according to the new period.

Parameters:

pTask	the periodic Task.
iNewPeriod	the new period between 2 iterations of the Task, in s.

void cairo_dock_relaunch_task_immediately	(	CairoDockTask *	pTask,
		int	iNewPeriod
	)

Change the frequency of a Task and relaunch it immediately. The next iteration is therefore immediately executed.

Parameters:

pTask	the periodic Task.
iNewPeriod	the new period between 2 iterations of the Task, in s, or -1 to let it unchanged.

void cairo_dock_downgrade_task_frequency ( CairoDockTask * pTask )

Downgrade the frequency of a Task. The Task will be executed less often (this is typically useful to put on stand-by a periodic measure).

Parameters:

pTask the periodic Task.

void cairo_dock_set_normal_task_frequency ( CairoDockTask * pTask )

Set the frequency of the Task to its normal state. This is also done automatically when launching the Task.

Parameters:

pTask the periodic Task.

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Function Documentation