AgsThread: Advanced Gtk+ Sequencer Reference Manual

AgsThread

AgsThread — threads

Functions

void	ags_thread_resume_handler ()
void	ags_thread_suspend_handler ()
void	ags_thread_set_sync ()
void	ags_thread_set_sync_all ()
void	ags_thread_lock ()
gboolean	ags_thread_trylock ()
void	ags_thread_unlock ()
AgsThread *	ags_thread_get_toplevel ()
AgsThread *	ags_thread_first ()
AgsThread *	ags_thread_last ()
void	ags_thread_remove_child ()
void	ags_thread_add_child ()
void	ags_thread_add_child_extended ()
gboolean	ags_thread_parental_is_locked ()
gboolean	ags_thread_sibling_is_locked ()
gboolean	ags_thread_children_is_locked ()
gboolean	ags_thread_is_current_ready ()
gboolean	ags_thread_is_tree_ready ()
AgsThread *	ags_thread_next_parent_locked ()
AgsThread *	ags_thread_next_sibling_locked ()
AgsThread *	ags_thread_next_children_locked ()
void	ags_thread_lock_parent ()
void	ags_thread_lock_sibling ()
void	ags_thread_lock_children ()
void	ags_thread_lock_all ()
void	ags_thread_unlock_parent ()
void	ags_thread_unlock_sibling ()
void	ags_thread_unlock_children ()
void	ags_thread_unlock_all ()
void	ags_thread_wait_parent ()
void	ags_thread_wait_sibling ()
void	ags_thread_wait_children ()
void	ags_thread_signal_parent ()
void	ags_thread_signal_sibling ()
void	ags_thread_signal_children ()
guint	ags_thread_clock ()
void	ags_thread_start ()
void	ags_thread_run ()
void	ags_thread_suspend ()
void	ags_thread_resume ()
void	ags_thread_timelock ()
void	ags_thread_stop ()
guint	ags_thread_interrupted ()
void	ags_thread_hangcheck ()
AgsThread *	ags_thread_find_type ()
AgsThread *	ags_thread_self ()
AgsThread *	ags_thread_chaos_tree ()
gboolean	ags_thread_is_chaos_tree ()
AgsThread *	ags_thread_new ()

Properties

gdouble

frequency

Read / Write

Signals

guint	clock	Run Last
guint	interrupted	Run Last
void	resume	Run Last
void	run	Run Last
void	start	Run Last
void	stop	Run Last
void	suspend	Run Last
void	timelock	Run Last

Types and Values

#define	AGS_THREAD_RESUME_SIG
#define	AGS_THREAD_SUSPEND_SIG
#define	AGS_RT_PRIORITY
#define	AGS_THREAD_HERTZ_JIFFIE
#define	AGS_THREAD_DEFAULT_JIFFIE
#define	AGS_THREAD_MAX_PRECISION
#define	AGS_THREAD_DEFAULT_ATTACK
enum	AgsThreadFlags
enum	AgsThreadSyncFlags

Object Hierarchy

    GObject
    ╰── AgsThread
        ├── AgsAudioLoop
        ├── AgsAudioThread
        ├── AgsAutosaveThread
        ├── AgsChannelThread
        ├── AgsExportThread
        ├── AgsGenericMainLoop
        ├── AgsGuiThread
        ├── AgsIteratorThread
        ├── AgsRecordThread
        ├── AgsRecyclingThread
        ├── AgsReturnableThread
        ├── AgsSequencerThread
        ├── AgsSimpleAutosaveThread
        ├── AgsSingleThread
        ├── AgsSoundcardThread
        ├── AgsTaskThread
        ╰── AgsTimestampThread

Implemented Interfaces

AgsThread implements AgsConnectable.

Includes

#include <ags/thread/ags_thread.h>

Description

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

Functions

ags_thread_resume_handler ()

void
ags_thread_resume_handler (int sig);

ags_thread_suspend_handler ()

void
ags_thread_suspend_handler (int sig);

ags_thread_set_sync ()

void
ags_thread_set_sync (AgsThread *thread,
                     guint tic);

Unsets AGS_THREAD_WAIT_0, AGS_THREAD_WAIT_1 or AGS_THREAD_WAIT_2. Additionaly the thread is woken up by this function if waiting.

Parameters

thread	an AgsThread
tic	the tic as sync occured.

Since: 0.4.0

ags_thread_set_sync_all ()

void
ags_thread_set_sync_all (AgsThread *thread,
                         guint tic);

Calls ags_thread_set_sync() on all threads.

Parameters

thread	an AgsThread
tic	the tic as sync occured.

Since: 0.4.0

ags_thread_lock ()

void
ags_thread_lock (AgsThread *thread);

Locks the threads own mutex and sets the appropriate flag.

Parameters

thread

an AgsThread

Since: 0.4.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

an AgsThread

Returns

TRUE on success, otherwise FALSE

Since: 0.4.0

ags_thread_unlock ()

void
ags_thread_unlock (AgsThread *thread);

Unlocks the threads own mutex and unsets the appropriate flag.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_get_toplevel ()

AgsThread *
ags_thread_get_toplevel (AgsThread *thread);

Retrieve toplevel thread.

Parameters

thread

an AgsThread

Returns

the toplevevel AgsThread

Since: 0.4.0

ags_thread_first ()

AgsThread *
ags_thread_first (AgsThread *thread);

Retrieve first sibling.

Parameters

thread

an AgsThread

Returns

the very first AgsThread within same tree level

Since: 0.4.0

ags_thread_last ()

AgsThread *
ags_thread_last (AgsThread *thread);

Retrieve last sibling.

Parameters

thread

an AgsThread

Returns

the very last AgsThread within same tree level

Since: 0.4.0

ags_thread_remove_child ()

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

Remove child of thread.

Parameters

thread	an AgsThread
child	the child to remove

Since: 0.4.0

ags_thread_add_child ()

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

Add child to thread.

Parameters

thread	an AgsThread
child	the child to remove

Since: 0.4.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	an AgsThread
child	the child to remove
no_start	don't start thread
no_wait	don't wait until started

Since: 0.4.2

ags_thread_parental_is_locked ()

gboolean
ags_thread_parental_is_locked (AgsThread *thread,
                               AgsThread *parent);

Check the AGS_THREAD_LOCKED flag in parental levels.

Parameters

thread	an AgsThread
parent	where to stop iteration

Returns

TRUE if locked otherwise FALSE

Since: 0.4.0

ags_thread_sibling_is_locked ()

gboolean
ags_thread_sibling_is_locked (AgsThread *thread);

Check the AGS_THREAD_LOCKED flag within sibling.

Parameters

thread

an AgsThread

Returns

TRUE if locked otherwise FALSE

Since: 0.4.0

ags_thread_children_is_locked ()

gboolean
ags_thread_children_is_locked (AgsThread *thread);

Check the AGS_THREAD_LOCKED flag within children.

Parameters

thread

an AgsThread

Returns

TRUE if locked otherwise FALSE

Since: 0.4.0

ags_thread_is_current_ready ()

gboolean
ags_thread_is_current_ready (AgsThread *current,
                             guint tic);

ags_thread_is_tree_ready ()

gboolean
ags_thread_is_tree_ready (AgsThread *thread,
                          guint tic);

ags_thread_next_parent_locked ()

AgsThread *
ags_thread_next_parent_locked (AgsThread *thread,
                               AgsThread *parent);

Retrieve next locked thread above thread .

Parameters

thread	an AgsThread
parent	the parent AgsThread where to stop.

Returns

next matching AgsThread

Since: 0.4.0

ags_thread_next_sibling_locked ()

AgsThread *
ags_thread_next_sibling_locked (AgsThread *thread);

Retrieve next locked thread neighbooring thread

Parameters

thread

an AgsThread

Returns

next matching AgsThread

Since: 0.4.0

ags_thread_next_children_locked ()

AgsThread *
ags_thread_next_children_locked (AgsThread *thread);

Retrieve next locked thread following thread

Parameters

thread

an AgsThread

Returns

next matching AgsThread

Since: 0.4.0

ags_thread_lock_parent ()

void
ags_thread_lock_parent (AgsThread *thread,
                        AgsThread *parent);

Lock parent tree structure.

Parameters

thread	an AgsThread
parent	the parent AgsThread where to stop.

Since: 0.4.0

ags_thread_lock_sibling ()

void
ags_thread_lock_sibling (AgsThread *thread);

Lock sibling tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_lock_children ()

void
ags_thread_lock_children (AgsThread *thread);

Lock child tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_lock_all ()

void
ags_thread_lock_all (AgsThread *thread);

ags_thread_unlock_parent ()

void
ags_thread_unlock_parent (AgsThread *thread,
                          AgsThread *parent);

Unlock parent tree structure.

Parameters

thread	an AgsThread
parent	the parent AgsThread where to stop.

Since: 0.4.0

ags_thread_unlock_sibling ()

void
ags_thread_unlock_sibling (AgsThread *thread);

Unlock sibling tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_unlock_children ()

void
ags_thread_unlock_children (AgsThread *thread);

Unlock child tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_unlock_all ()

void
ags_thread_unlock_all (AgsThread *thread);

ags_thread_wait_parent ()

void
ags_thread_wait_parent (AgsThread *thread,
                        AgsThread *parent);

Wait on parent tree structure.

Parameters

thread	an AgsThread
parent	the parent AgsThread where to stop.

Since: 0.4.0

ags_thread_wait_sibling ()

void
ags_thread_wait_sibling (AgsThread *thread);

Wait on sibling tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_wait_children ()

void
ags_thread_wait_children (AgsThread *thread);

Wait on child tree structure.

Parameters

thread

an AgsThread

Since: 0.4.0

ags_thread_signal_parent ()

void
ags_thread_signal_parent (AgsThread *thread,
                          AgsThread *parent,
                          gboolean broadcast);

Signals the tree in higher levels.

Parameters

thread	an AgsThread
parent	the parent AgsThread
broadcast	whether to perforam a signal or to broadcast

Since: 0.4.0

ags_thread_signal_sibling ()

void
ags_thread_signal_sibling (AgsThread *thread,
                           gboolean broadcast);

Signals the tree on same level.

Parameters

thread	an AgsThread
broadcast	whether to perforam a signal or to broadcast

Since: 0.4.0

ags_thread_signal_children ()

void
ags_thread_signal_children (AgsThread *thread,
                            gboolean broadcast);

Signals the tree in lower levels.

Parameters

thread	an AgsThread
broadcast	whether to perforam a signal or to broadcast

Since: 0.4.0

ags_thread_clock ()

guint
ags_thread_clock (AgsThread *thread);

Clock the thread.

Parameters

thread

the AgsThread instance

Returns

the number of cycles to perform.

Since: 0.4.0

ags_thread_start ()

void
ags_thread_start (AgsThread *thread);

Start the thread.

Parameters

thread

the AgsThread instance

Since: 0.4.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 instance

Since: 0.4.0

ags_thread_suspend ()

void
ags_thread_suspend (AgsThread *thread);

ags_thread_resume ()

void
ags_thread_resume (AgsThread *thread);

ags_thread_timelock ()

void
ags_thread_timelock (AgsThread *thread);

ags_thread_stop ()

void
ags_thread_stop (AgsThread *thread);

Stop the threads loop by unsetting AGS_THREAD_RUNNING flag.

Parameters

thread

the AgsThread instance

Since: 0.4.0

ags_thread_interrupted ()

guint
ags_thread_interrupted (AgsThread *thread,
                        int sig,
                        guint time_cycle,
                        guint *time_spent);

Notify to resume interrupted thread.

Parameters

thread	the AgsThread
sig	signal number
time_cycle	duration of the time cycle
time_spent	time spent since last cycle

Returns

the time spent

Since: 0.7.46

ags_thread_hangcheck ()

void
ags_thread_hangcheck (AgsThread *thread);

Performs hangcheck of thread.

Parameters

thread

the AgsThread instance

Since: 0.4.0

ags_thread_find_type ()

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

ags_thread_self ()

AgsThread *
ags_thread_self (void);

ags_thread_chaos_tree ()

AgsThread *
ags_thread_chaos_tree (AgsThread *thread);

Escape chaos tree, get syncing point.

Parameters

thread

the AgsThread

Returns

the first ordered thread

Since: 0.7.40

ags_thread_is_chaos_tree ()

gboolean
ags_thread_is_chaos_tree (AgsThread *thread,
                          guint tic_delay,
                          gboolean is_chaos_tree);

Check chaos tree and flag threads.

Parameters

thread	the AgsThread
tic_delay	the tic to sync with
is_chaos_tree	if `TRUE` AGS_THREAD_IS_CHAOS_TREE flag is set

Returns

TRUE if tree is in chaos, otherwise FALSE

Since: 0.7.43

ags_thread_new ()

AgsThread *
ags_thread_new (gpointer data);

Create a new AgsThread you may provide a gpointer as data to your thread routine.

Parameters

data

an GObject

Returns

the new AgsThread

Since: 0.4.0

Types and Values

AGS_THREAD_RESUME_SIG

#define AGS_THREAD_RESUME_SIG SIGUSR2

AGS_THREAD_SUSPEND_SIG

#define AGS_THREAD_SUSPEND_SIG SIGUSR1

AGS_RT_PRIORITY

#define AGS_RT_PRIORITY (45)

AGS_THREAD_HERTZ_JIFFIE

#define AGS_THREAD_HERTZ_JIFFIE (1000.0)

AGS_THREAD_DEFAULT_JIFFIE

#define AGS_THREAD_DEFAULT_JIFFIE (1000.0)

AGS_THREAD_MAX_PRECISION

#define AGS_THREAD_MAX_PRECISION (1000.0)

AGS_THREAD_DEFAULT_ATTACK

#define AGS_THREAD_DEFAULT_ATTACK (1.0)

enum AgsThreadFlags

Members

AGS_THREAD_CONNECTED
AGS_THREAD_SINGLE_LOOP
AGS_THREAD_INITIAL_SYNC
AGS_THREAD_INITIAL_RUN
AGS_THREAD_RT_SETUP
AGS_THREAD_WAITING
AGS_THREAD_RUNNING
AGS_THREAD_IDLE
AGS_THREAD_LOCKED
AGS_THREAD_SUSPENDED
AGS_THREAD_READY
AGS_THREAD_UNREF_ON_EXIT
AGS_THREAD_IS_CHAOS_TREE
AGS_THREAD_IMMEDIATE_SYNC
AGS_THREAD_RECOVER_INTERRUPTED
AGS_THREAD_RESUME_INTERRUPTED

enum AgsThreadSyncFlags

Members

AGS_THREAD_WAIT_FOR_PARENT
AGS_THREAD_WAIT_FOR_SIBLING
AGS_THREAD_WAIT_FOR_CHILDREN
AGS_THREAD_WAIT_FOR_BARRIER
AGS_THREAD_WAITING_FOR_PARENT
AGS_THREAD_WAITING_FOR_SIBLING
AGS_THREAD_WAITING_FOR_CHILDREN
AGS_THREAD_WAITING_FOR_BARRIER
AGS_THREAD_BROADCAST_PARENT
AGS_THREAD_BROADCAST_SIBLING
AGS_THREAD_BROADCAST_CHILDREN
AGS_THREAD_TREE_SYNC_0
AGS_THREAD_WAIT_0
AGS_THREAD_TREE_SYNC_1
AGS_THREAD_WAIT_1
AGS_THREAD_TREE_SYNC_2
AGS_THREAD_WAIT_2
AGS_THREAD_TIMELOCK_RUN
AGS_THREAD_TIMELOCK_WAIT
AGS_THREAD_TIMELOCK_RESUME
AGS_THREAD_SKIP_NON_GREEDY
AGS_THREAD_SKIPPED_BY_TIMELOCK
AGS_THREAD_LOCK_GREEDY_RUN_MUTEX
AGS_THREAD_START_SYNCED_FREQ
AGS_THREAD_SYNCED_FREQ
AGS_THREAD_INTERRUPTED
AGS_THREAD_MONITORING

Property Details

The `“frequency”` property

  “frequency”                gdouble

JIFFIE.

Flags: Read / Write

Allowed values: [0.01,1000]

Default value: 1000

Since: 0.4.0

Signal Details

The `“clock”` signal

guint
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.6.0

The `“interrupted”` signal

guint
user_function (AgsThread *thread,
               gint       sig,
               guint      time_cycle,
               gpointer   time_spent,
               gpointer   user_data)

Flags: Run Last

Since: 0.7.46

The `“resume”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0

The `“run”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0

The `“start”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0

The `“stop”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0

The `“suspend”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0

The `“timelock”` signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

Flags: Run Last

Since: 0.5.0