AgsThread: Advanced Gtk+ Sequencer Reference Manual

AgsThread

AgsThread — thread class with base frequency

Stability Level

Stable, unless otherwise indicated

Functions

#define	AGS_THREAD_GET_OBJ_MUTEX()
#define	AGS_THREAD_GET_WAIT_MUTEX()
#define	AGS_THREAD_GET_WAIT_COND()
#define	AGS_THREAD_GET_TIC_MUTEX()
#define	AGS_THREAD_GET_TIC_COND()
#define	AGS_THREAD_GET_START_MUTEX()
#define	AGS_THREAD_GET_START_COND()
gboolean	ags_thread_global_get_use_sync_counter ()
gboolean	ags_thread_test_flags ()
void	ags_thread_set_flags ()
void	ags_thread_unset_flags ()
gboolean	ags_thread_test_status_flags ()
void	ags_thread_set_status_flags ()
void	ags_thread_unset_status_flags ()
void	ags_thread_clear_status_flags ()
gboolean	ags_thread_test_sync_tic_flags ()
void	ags_thread_set_sync_tic_flags ()
void	ags_thread_unset_sync_tic_flags ()
void	ags_thread_clear_sync_tic_flags ()
void	ags_thread_set_current_sync_tic ()
guint	ags_thread_get_current_sync_tic ()
void	ags_thread_set_delay ()
gdouble	ags_thread_get_delay ()
void	ags_thread_set_frequency ()
gdouble	ags_thread_get_frequency ()
void	ags_thread_set_max_precision ()
gdouble	ags_thread_get_max_precision ()
AgsThread *	ags_thread_find_type ()
AgsThread *	ags_thread_self ()
AgsThread *	ags_thread_parent ()
AgsThread *	ags_thread_next ()
AgsThread *	ags_thread_prev ()
AgsThread *	ags_thread_children ()
AgsThread *	ags_thread_get_toplevel ()
AgsThread *	ags_thread_first ()
AgsThread *	ags_thread_last ()
void	ags_thread_lock ()
gboolean	ags_thread_trylock ()
void	ags_thread_unlock ()
void	ags_thread_remove_child ()
void	ags_thread_add_child ()
void	ags_thread_add_child_extended ()
gboolean	ags_thread_is_current_ready ()
gboolean	ags_thread_is_tree_ready_recursive ()
void	ags_thread_prepare_current_sync ()
void	ags_thread_prepare_tree_sync_recursive ()
void	ags_thread_set_current_sync ()
void	ags_thread_set_tree_sync_recursive ()
guint	ags_thread_clock ()
void	ags_thread_add_start_queue ()
void	ags_thread_add_start_queue_all ()
void	ags_thread_start ()
void	ags_thread_run ()
void	ags_thread_stop ()
AgsThread *	ags_thread_new ()

Properties

double	delay	Read / Write
double	frequency	Read / Write
double	max-precision	Read / Write

Signals

guint	clock	Run Last
void	run	Run Last
void	start	Run Last
void	stop	Run Last

Types and Values

#define	AGS_THREAD_HERTZ_JIFFIE
#define	AGS_THREAD_YIELD_JIFFIE
#define	AGS_THREAD_DEFAULT_JIFFIE
#define	AGS_THREAD_DEFAULT_MAX_PRECISION
#define	AGS_THREAD_MAX_PRECISION
#define	AGS_THREAD_DEFAULT_ATTACK
#define	AGS_THREAD_TOLERANCE
enum	AgsThreadFlags
enum	AgsThreadStatusFlags
enum	AgsThreadSyncTicFlags

Object Hierarchy

    GFlags
    ├── AgsThreadFlags
    ├── AgsThreadStatusFlags
    ╰── AgsThreadSyncTicFlags
    GObject
    ╰── AgsThread
        ├── AgsWorkerThread
        ├── AgsGenericMainLoop
        ╰── AgsReturnableThread

Includes

#include <ags/thread/ags_thread.h>

Description

The AgsThread base class. It supports organizing them within a tree, perform syncing and frequencies.

The thread class synchronizes within tree at max-precision property JIFFIE. AgsThread::run() is called at frequency property JIFFIE.

The AgsThread::run() function can sync to the very same tic with AGS_THREAD_IMMEDIATE_SYNC flag, sync to the previous or next tic with AGS_THREAD_INTERMEDIATE_PRE_SYNC or AGS_THREAD_INTERMEDIATE_POST_SYNC flag set.

The AgsTread::clock() function is called at max-precision property rate per second.

Note you usually have a default source giving you timing hints i.e. poll is used. If not you can still set the AGS_THREAD_TIME_ACCOUNTING flags, causing a sleep for every tic.

Further there is no time promise within one second. But you should make sure you hit the real-time dead-line or use a worker thread instead for time expensive work or tasks.

ags_thread_self() returns you your own AgsThread you are running in or NULL if not applicable.

To create a new thread, connect AgsThread::run() and attach it to main loop use the following example:

AgsThread *main_loop;
AgsThread *thread;

AgsApplicationContext *application_context;

gdouble frequency;

ags_thread_application_context_new();

application_context = ags_application_context_get_instance();

main_loop = ags_concurrency_provider_get_main_loop(AGS_CONCURRENCY_PROVIDER(application_context));

frequency = 0.004; // frequency equals to 0.004 causes AgsThread::run() to be emitted 250 times per second.

thread = ags_thread_new();
ags_thread_set_frequency(thread,
                         frequency);

g_signal_connect(thread, "run",
                 G_CALLBACK(my_app_run_callback), my_data);

ags_thread_add_start_queue(main_loop,
                           thread);

Functions

AGS_THREAD_GET_OBJ_MUTEX()

#define AGS_THREAD_GET_OBJ_MUTEX(obj) (&(((AgsThread *) obj)->obj_mutex))

AGS_THREAD_GET_WAIT_MUTEX()

#define AGS_THREAD_GET_WAIT_MUTEX(obj) (&(((AgsThread *) obj)->wait_mutex))

AGS_THREAD_GET_WAIT_COND()

#define AGS_THREAD_GET_WAIT_COND(obj) (&(((AgsThread *) obj)->wait_cond))

AGS_THREAD_GET_TIC_MUTEX()

#define AGS_THREAD_GET_TIC_MUTEX(obj) (&(((AgsThread *) obj)->tic_mutex))

AGS_THREAD_GET_TIC_COND()

#define AGS_THREAD_GET_TIC_COND(obj) (&(((AgsThread *) obj)->tic_cond))

AGS_THREAD_GET_START_MUTEX()

#define AGS_THREAD_GET_START_MUTEX(obj) (&(((AgsThread *) obj)->start_mutex))

AGS_THREAD_GET_START_COND()

#define AGS_THREAD_GET_START_COND(obj) (&(((AgsThread *) obj)->start_cond))

ags_thread_global_get_use_sync_counter ()

gboolean
ags_thread_global_get_use_sync_counter
                               ();

Get global config value use sync counter.

Returns

if TRUE use sync counter, else not

Since: 3.0.0

ags_thread_test_flags ()

gboolean
ags_thread_test_flags (AgsThread *thread,
                       AgsThreadFlags flags);

Test flags to be set on thread .

Parameters

thread	the AgsThread
flags	the flags

Returns

TRUE if flags are set, else FALSE

Since: 3.0.0

ags_thread_set_flags ()

void
ags_thread_set_flags (AgsThread *thread,
                      AgsThreadFlags flags);

Set flags.

Parameters

thread	the AgsThread
flags	the flags

Since: 3.0.0

ags_thread_unset_flags ()

void
ags_thread_unset_flags (AgsThread *thread,
                        AgsThreadFlags flags);

Unset flags.

Parameters

thread	the AgsThread
flags	the flags

Since: 3.0.0

ags_thread_test_status_flags ()

gboolean
ags_thread_test_status_flags (AgsThread *thread,
                              AgsThreadStatusFlags status_flags);

Test status_flags to be set on thread .

Parameters

thread	the AgsThread
status_flags	the status flags

Returns

TRUE if status flags are set, else FALSE

Since: 3.0.0

ags_thread_set_status_flags ()

void
ags_thread_set_status_flags (AgsThread *thread,
                             AgsThreadStatusFlags status_flags);

Set status flags.

Parameters

thread	the AgsThread
status_flags	the status flags

Since: 3.0.0

ags_thread_unset_status_flags ()

void
ags_thread_unset_status_flags (AgsThread *thread,
                               AgsThreadStatusFlags status_flags);

Unset status flags.

Parameters

thread	the AgsThread
status_flags	the status flags

Since: 3.0.0

ags_thread_clear_status_flags ()

void
ags_thread_clear_status_flags (AgsThread *thread);

Clear status flags.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_test_sync_tic_flags ()

gboolean
ags_thread_test_sync_tic_flags (AgsThread *thread,
                                AgsThreadSyncTicFlags sync_tic_flags);

Test sync_tic_flags to be set on thread .

Parameters

thread	the AgsThread
sync_tic_flags	the sync-tic flags

Returns

TRUE if sync-tic flags are set, else FALSE

Since: 3.0.0

ags_thread_set_sync_tic_flags ()

void
ags_thread_set_sync_tic_flags (AgsThread *thread,
                               AgsThreadSyncTicFlags sync_tic_flags);

Set sync-tic flags.

Parameters

thread	the AgsThread
sync_tic_flags	the sync-tic flags

Since: 3.0.0

ags_thread_unset_sync_tic_flags ()

void
ags_thread_unset_sync_tic_flags (AgsThread *thread,
                                 AgsThreadSyncTicFlags sync_tic_flags);

Unset sync-tic flags.

Parameters

thread	the AgsThread
sync_tic_flags	the sync-tic flags

Since: 3.0.0

ags_thread_clear_sync_tic_flags ()

void
ags_thread_clear_sync_tic_flags (AgsThread *thread);

Clear sync-tic flags.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_set_current_sync_tic ()

void
ags_thread_set_current_sync_tic (AgsThread *thread,
                                 guint current_sync_tic);

Set current sync-tic.

Parameters

thread	the AgsThread
current_sync_tic	the current sync-tic

Since: 3.0.0

ags_thread_get_current_sync_tic ()

guint
ags_thread_get_current_sync_tic (AgsThread *thread);

Get current sync-tic.

Parameters

thread

the AgsThread

Returns

the current sync-tic

Since: 3.0.0

ags_thread_set_delay ()

void
ags_thread_set_delay (AgsThread *thread,
                      gdouble delay);

Set delay.

Parameters

thread	the AgsThread
delay	the delay

Since: 3.0.0

ags_thread_get_delay ()

gdouble
ags_thread_get_delay (AgsThread *thread);

Get delay.

Parameters

thread

the AgsThread

Returns

the delay

Since: 3.0.0

ags_thread_set_frequency ()

void
ags_thread_set_frequency (AgsThread *thread,
                          gdouble frequency);

Set frequency.

Parameters

thread	the AgsThread
frequency	the frequency

Since: 3.0.0

ags_thread_get_frequency ()

gdouble
ags_thread_get_frequency (AgsThread *thread);

Get frequency.

Parameters

thread

the AgsThread

Returns

the frequency

Since: 3.0.0

ags_thread_set_max_precision ()

void
ags_thread_set_max_precision (AgsThread *thread,
                              gdouble max_precision);

Set max-precision.

Parameters

thread	the AgsThread
max_precision	the max-precision

Since: 3.0.0

ags_thread_get_max_precision ()

gdouble
ags_thread_get_max_precision (AgsThread *thread);

Get max-precision.

Parameters

thread

the AgsThread

Returns

the max-precision

Since: 3.0.0

ags_thread_find_type ()

AgsThread *
ags_thread_find_type (AgsThread *thread,
                      GType gtype);

Find gtype as descendant of thread . If its a descendant thread, the ref-count is increased.

Parameters

thread	the AgsThread
gtype	the GType

Returns

the matching AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_self ()

AgsThread *
ags_thread_self (void);

Thread self.

Returns

the running AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_parent ()

AgsThread *
ags_thread_parent (AgsThread *thread);

Get parent thread.

Parameters

thread

the AgsThread

Returns

the parent AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_next ()

AgsThread *
ags_thread_next (AgsThread *thread);

Get next thread.

Parameters

thread

the AgsThread

Returns

the next AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_prev ()

AgsThread *
ags_thread_prev (AgsThread *thread);

Get prev thread.

Parameters

thread

the AgsThread

Returns

the prev AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_children ()

AgsThread *
ags_thread_children (AgsThread *thread);

Get children thread.

Parameters

thread

the AgsThread

Returns

the children AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_get_toplevel ()

AgsThread *
ags_thread_get_toplevel (AgsThread *thread);

Retrieve toplevel thread.

Parameters

thread

the AgsThread

Returns

the toplevevel AgsThread.

[transfer full]

Since: 3.0.0

ags_thread_first ()

AgsThread *
ags_thread_first (AgsThread *thread);

Retrieve first sibling.

Parameters

thread

the AgsThread

Returns

the very first AgsThread within same tree level.

[transfer full]

Since: 3.0.0

ags_thread_last ()

AgsThread *
ags_thread_last (AgsThread *thread);

Retrieve last sibling.

Parameters

thread

the AgsThread

Returns

the very last AgsThread within same tree level.

[transfer full]

Since: 3.0.0

ags_thread_lock ()

void
ags_thread_lock (AgsThread *thread);

Locks the threads own mutex and sets the appropriate flag.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_trylock ()

gboolean
ags_thread_trylock (AgsThread *thread);

Locks the threads own mutex if available and sets the appropriate flag and returning TRUE. Otherwise return FALSE without lock.

Parameters

thread

the AgsThread

Returns

TRUE on success, otherwise FALSE

Since: 3.0.0

ags_thread_unlock ()

void
ags_thread_unlock (AgsThread *thread);

Unlocks the threads own mutex and unsets the appropriate flag.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_remove_child ()

void
ags_thread_remove_child (AgsThread *thread,
                         AgsThread *child);

Remove child of thread.

Parameters

thread	the AgsThread
child	the child to remove

Since: 3.0.0

ags_thread_add_child ()

void
ags_thread_add_child (AgsThread *thread,
                      AgsThread *child);

Add child to thread.

Parameters

thread	the AgsThread
child	the child to remove

Since: 3.0.0

ags_thread_add_child_extended ()

void
ags_thread_add_child_extended (AgsThread *thread,
                               AgsThread *child,
                               gboolean no_start,
                               gboolean no_wait);

Add child to thread.

Parameters

thread	the AgsThread
child	the child to remove
no_start	don't start thread
no_wait	don't wait until started

Since: 3.0.0

ags_thread_is_current_ready ()

gboolean
ags_thread_is_current_ready (AgsThread *current,
                             guint current_sync_tic);

ags_thread_is_tree_ready_recursive ()

gboolean
ags_thread_is_tree_ready_recursive (AgsThread *thread,
                                    guint current_sync_tic);

ags_thread_prepare_current_sync ()

void
ags_thread_prepare_current_sync (AgsThread *current,
                                 guint current_sync_tic);

ags_thread_prepare_tree_sync_recursive ()

void
ags_thread_prepare_tree_sync_recursive
                               (AgsThread *thread,
                                guint current_sync_tic);

ags_thread_set_current_sync ()

void
ags_thread_set_current_sync (AgsThread *current,
                             guint current_sync_tic);

ags_thread_set_tree_sync_recursive ()

void
ags_thread_set_tree_sync_recursive (AgsThread *thread,
                                    guint current_sync_tic);

ags_thread_clock ()

guint
ags_thread_clock (AgsThread *thread);

Clock the thread.

Parameters

thread

the AgsThread instance

Returns

the cycles to be performed

Since: 3.0.0

ags_thread_add_start_queue ()

void
ags_thread_add_start_queue (AgsThread *thread,
                            AgsThread *child);

Add child to thread 's start queue.

Parameters

thread	the AgsThread
child	the child AgsThread to start

Since: 3.0.0

ags_thread_add_start_queue_all ()

void
ags_thread_add_start_queue_all (AgsThread *thread,
                                GList *child);

Add child to thread 's start queue.

Parameters

thread	the AgsThread
child	the children as GList containing AgsThread to start.	[element-type Ags.Thread]

Since: 3.0.0

ags_thread_start ()

void
ags_thread_start (AgsThread *thread);

Start the thread.

Parameters

thread

the AgsThread instance

Since: 3.0.0

ags_thread_run ()

void
ags_thread_run (AgsThread *thread);

Only for internal use of ags_thread_loop but you may want to set the your very own class function namely your thread's routine.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_stop ()

void
ags_thread_stop (AgsThread *thread);

Stop the threads loop by unsetting AGS_THREAD_STATUS_RUNNING flag.

Parameters

thread

the AgsThread

Since: 3.0.0

ags_thread_new ()

AgsThread *
ags_thread_new ();

Create a new instance of AgsThread.

Returns

the new AgsThread

Since: 3.0.0

Types and Values

AGS_THREAD_HERTZ_JIFFIE

#define AGS_THREAD_HERTZ_JIFFIE (1000.0)

AGS_THREAD_YIELD_JIFFIE

#define AGS_THREAD_YIELD_JIFFIE (2.0)

AGS_THREAD_DEFAULT_JIFFIE

#define AGS_THREAD_DEFAULT_JIFFIE (250.0)

AGS_THREAD_DEFAULT_MAX_PRECISION

#define AGS_THREAD_DEFAULT_MAX_PRECISION (1000.0)

AGS_THREAD_MAX_PRECISION

#define AGS_THREAD_MAX_PRECISION (1000.0)

AGS_THREAD_DEFAULT_ATTACK

#define AGS_THREAD_DEFAULT_ATTACK (1.0)

AGS_THREAD_TOLERANCE

#define AGS_THREAD_TOLERANCE (0.0)

enum AgsThreadFlags

Enum values to control the behavior or indicate internal state of AgsThread by enable/disable as flags.

Members

AGS_THREAD_UNREF_ON_EXIT	call `g_object_unref()` before `g_thread_exit()`
AGS_THREAD_IMMEDIATE_SYNC	do sync immediately
AGS_THREAD_INTERMEDIATE_PRE_SYNC	intermediate pre sync to parent thread
AGS_THREAD_INTERMEDIATE_POST_SYNC	intermediate post sync to parent thread
AGS_THREAD_START_SYNCED_FREQ	sync frequency as starting thread
AGS_THREAD_MARK_SYNCED	mark thread synced
AGS_THREAD_TIME_ACCOUNTING	time accounting causes to track time

enum AgsThreadStatusFlags

Enum values to control the behavior or indicate internal state of AgsThread by enable/disable as status flags.

Members

AGS_THREAD_STATUS_RT_SETUP	realtime setup was performed
AGS_THREAD_STATUS_INITIAL_SYNC	initial sync indicates the thread wasn't synced before
AGS_THREAD_STATUS_INITIAL_RUN	the first call to `AgsThread:run()`
AGS_THREAD_STATUS_IS_CHAOS_TREE	the thread is not synced
AGS_THREAD_STATUS_START_WAIT	the thread start is waiting
AGS_THREAD_STATUS_START_DONE	the thread start is done
AGS_THREAD_STATUS_READY	the thread is ready
AGS_THREAD_STATUS_WAITING	the thread is waiting
AGS_THREAD_STATUS_RUNNING	the thread is running
AGS_THREAD_STATUS_LOCKED	the thread is locked
AGS_THREAD_STATUS_BUSY	the thread is busy
AGS_THREAD_STATUS_SYNCED	the thread joined the tic based system, it is synced
AGS_THREAD_STATUS_SYNCED_FREQ	the frequency was synced

enum AgsThreadSyncTicFlags

Enum values to control the behavior or indicate internal state of AgsThread by enable/disable as sync tic flags.

Members

AGS_THREAD_SYNC_TIC_WAIT_0	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_0	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_1	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_1	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_2	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_2	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_3	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_3	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_4	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_4	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_5	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_5	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_6	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_6	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_7	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_7	done tree to be synced
AGS_THREAD_SYNC_TIC_WAIT_8	wait tree to be synced
AGS_THREAD_SYNC_TIC_DONE_8	done tree to be synced

Property Details

The `“delay”` property

  “delay”                    double

The delay until next tic.

Owner: AgsThread

Flags: Read / Write

Allowed values: [1,1000]

Default value: 1

Since: 3.0.0

The `“frequency”` property

  “frequency”                double

The frequency to run at in Hz.

Owner: AgsThread

Flags: Read / Write

Allowed values: [0.01,1000]

Default value: 250

Since: 3.0.0

The `“max-precision”` property

  “max-precision”            double

The max-frequency to run at in Hz.

Owner: AgsThread

Flags: Read / Write

Allowed values: [0.01,1000]

Default value: 1000

Since: 3.0.0

Signal Details

The `“clock”` signal

guint
user_function (AgsThread *thread,
               gpointer   user_data)

The ::clock() signal is invoked every thread tic.

Parameters

thread	the AgsThread
user_data	user data set when the signal handler was connected.

Returns

the number of cycles to perform

Flags: Run Last

Since: 3.0.0

The `“run”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::run() signal is invoked during run loop.

Parameters

thread	the AgsThread
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“start”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::start() signal is invoked as thread started.

Parameters

thread	the AgsThread
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“stop”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::stop() signal is invoked as thread stopped.

Parameters

thread	the AgsThread
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0