cairo-dock-task.h File Reference

Data Structures
struct	_GldiTask
	Definition of a periodic and/or asynchronous Task. More...

Macros
#define	gldi_task_new(iPeriod, get_data, update, pSharedMemory)
#define	gldi_task_get_elapsed_time(pTask)

Typedefs
typedef void(*	GldiGetDataAsyncFunc )(gpointer pSharedMemory)
	Definition of the asynchronous job, that does the heavy part.
typedef gboolean(*	GldiUpdateSyncFunc )(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.

Functions
void	gldi_task_launch (GldiTask *pTask)
void	gldi_task_launch_delayed (GldiTask *pTask, double fDelay)
GldiTask *	gldi_task_new_full (int iPeriod, GldiGetDataAsyncFunc get_data, GldiUpdateSyncFunc update, GFreeFunc free_data, gpointer pSharedMemory)
void	gldi_task_stop (GldiTask *pTask)
void	gldi_task_discard (GldiTask *pTask)
void	gldi_task_free (GldiTask *pTask)
gboolean	gldi_task_is_active (GldiTask *pTask)
gboolean	gldi_task_is_running (GldiTask *pTask)
void	gldi_task_change_frequency (GldiTask *pTask, int iNewPeriod)
void	gldi_task_change_frequency_and_relaunch (GldiTask *pTask, int iNewPeriod)
void	gldi_task_downgrade_frequency (GldiTask *pTask)
void	gldi_task_set_normal_frequency (GldiTask *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 gldi_task_new, launch it with gldi_task_launch, and destroy it with gldi_task_free or gldi_task_discard.

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.

Macro Definition Documentation

#define gldi_task_new	(		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 gldi_task_launch. Free it with gldi_task_free or gldi_task_discard.

#define gldi_task_get_elapsed_time

(

pTask

)

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

Parameters

pTask

the periodic Task.

Function Documentation

void gldi_task_launch

(

GldiTask *

pTask

)

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

Parameters

pTask

the periodic Task.

void gldi_task_launch_delayed	(	GldiTask *	pTask,
		double	fDelay
	)

Same as above but after a delay. If the delay is 0, the task will be launched as soon as the main loop becomes idle.

Parameters

pTask	the periodic Task.
fDelay	delay in ms.

GldiTask* gldi_task_new_full	(	int	iPeriod,
		GldiGetDataAsyncFunc	get_data,
		GldiUpdateSyncFunc	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 gldi_task_launch. Free it with gldi_task_free or gldi_task_discard.

void gldi_task_stop

(

GldiTask *

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

Parameters

pTask

the periodic Task.

void gldi_task_discard

(

GldiTask *

pTask

)

Discard a periodic Task. The asynchronous thread will continue, and the Task will be freed when it ends. The Task should be considered as destroyed after a call to this function. This function can be used inside the 'update' callback to destroy the Task.

Parameters

pTask

the periodic Task.

void gldi_task_free

(

GldiTask *

pTask

)

Stop and destroy a periodic Task, freeing all the allocated ressources. Unlike gldi_task_discard, 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 gldi_task_discard instead.

Parameters

pTask

the periodic Task.

gboolean gldi_task_is_active

(

GldiTask *

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 gldi_task_is_running

(

GldiTask *

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 gldi_task_change_frequency	(	GldiTask *	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 gldi_task_change_frequency_and_relaunch	(	GldiTask *	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 gldi_task_downgrade_frequency

(

GldiTask *

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 gldi_task_set_normal_frequency

(

GldiTask *

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.