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_reset_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_add_start_queue ()
void ags_thread_add_start_queue_all ()
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 ()
#define AGS_IS_THREAD()
#define AGS_THREAD()
#define AGS_THREAD_CLASS()
#define AGS_THREAD_GET_CLASS()
GType ags_thread_get_type ()

Properties

gdouble frequency Read / Write
gdouble max-precision Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── AgsThread
        ├── AgsAutosaveThread
        ├── AgsWorkerThread
        ├── AgsGenericMainLoop
        ├── AgsPollingThread
        ├── AgsTaskThread
        ├── AgsReturnableThread
        ├── AgsSingleThread
        ╰── 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: 1.0.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: 1.0.0


ags_thread_reset_all ()

void
ags_thread_reset_all (AgsThread *thread);

Reset all threads. E.g. suspended threads. A synchronization stage after AgsAsyncQueue run.

Parameters

thread

the AgsThread

 

Since: 1.0.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: 1.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

an AgsThread

 

Returns

TRUE on success, otherwise FALSE

Since: 1.0.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: 1.0.0


ags_thread_get_toplevel ()

AgsThread *
ags_thread_get_toplevel (AgsThread *thread);

Retrieve toplevel thread.

Parameters

thread

an AgsThread

 

Returns

the toplevevel AgsThread

Since: 1.0.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: 1.0.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: 1.0.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: 1.0.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: 1.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

an AgsThread

 

child

the child to remove

 

no_start

don't start thread

 

no_wait

don't wait until started

 

Since: 1.0.0


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: 1.0.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: 1.0.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: 1.0.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: 1.0.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: 1.0.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: 1.0.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: 1.0.0


ags_thread_lock_sibling ()

void
ags_thread_lock_sibling (AgsThread *thread);

Lock sibling tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.0


ags_thread_lock_children ()

void
ags_thread_lock_children (AgsThread *thread);

Lock child tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.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: 1.0.0


ags_thread_unlock_sibling ()

void
ags_thread_unlock_sibling (AgsThread *thread);

Unlock sibling tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.0


ags_thread_unlock_children ()

void
ags_thread_unlock_children (AgsThread *thread);

Unlock child tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.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: 1.0.0


ags_thread_wait_sibling ()

void
ags_thread_wait_sibling (AgsThread *thread);

Wait on sibling tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.0


ags_thread_wait_children ()

void
ags_thread_wait_children (AgsThread *thread);

Wait on child tree structure.

Parameters

thread

an AgsThread

 

Since: 1.0.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: 1.0.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: 1.0.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: 1.0.0


ags_thread_clock ()

guint
ags_thread_clock (AgsThread *thread);

Clock the thread.

Parameters

thread

the AgsThread instance

 

Returns

the cycles to be performed

Since: 1.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 children as GList containing AgsThread to start

 

Since: 1.0.0


ags_thread_add_start_queue_all ()

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

ags_thread_start ()

void
ags_thread_start (AgsThread *thread);

Start the thread.

Parameters

thread

the AgsThread instance

 

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

 

Since: 1.0.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: 1.0.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: 1.0.0


ags_thread_hangcheck ()

void
ags_thread_hangcheck (AgsThread *thread);

Performs hangcheck of thread.

Parameters

thread

the AgsThread instance

 

Since: 1.0.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: 1.0.0


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: 1.0.0


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: 1.0.0


AGS_IS_THREAD()

#define AGS_IS_THREAD(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), AGS_TYPE_THREAD))

AGS_THREAD()

#define AGS_THREAD(obj)                (G_TYPE_CHECK_INSTANCE_CAST((obj), AGS_TYPE_THREAD, AgsThread))

AGS_THREAD_CLASS()

#define AGS_THREAD_CLASS(class)        (G_TYPE_CHECK_CLASS_CAST(class, AGS_TYPE_THREAD, AgsThreadClass))

AGS_THREAD_GET_CLASS()

#define AGS_THREAD_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS(obj, AGS_TYPE_THREAD, AgsThreadClass))

ags_thread_get_type ()

GType
ags_thread_get_type ();

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

the thread was connected by AgsConnectable::connect()

 

AGS_THREAD_SINGLE_LOOP

the thread doesn't actually run in its owns thread

 

AGS_THREAD_INITIAL_SYNC

initial sync indicates the thread wasn't synced before

 

AGS_THREAD_INITIAL_RUN

the first call to AgsThread:run()

 

AGS_THREAD_RT_SETUP

realtime setup was performed

 

AGS_THREAD_WAITING

the thread is waiting

 

AGS_THREAD_RUNNING

the thread is running

 

AGS_THREAD_IDLE

the thread is in idle mode

 

AGS_THREAD_LOCKED

the thread is locked

 

AGS_THREAD_SUSPENDED

the thread is suspended

 

AGS_THREAD_READY

the thread is ready

 

AGS_THREAD_UNREF_ON_EXIT

call g_object_unref() before pthread_exit()

 

AGS_THREAD_IS_CHAOS_TREE

the thread is not synced

 

AGS_THREAD_IMMEDIATE_SYNC

do sync immediately

 

AGS_THREAD_RECOVER_INTERRUPTED

check if thread was interrupted

 

AGS_THREAD_RESUME_INTERRUPTED

call ags_thread_resume() if AGS_THREAD_SUSPENDED is set

 

AGS_THREAD_TIMING

do timing

 

AGS_THREAD_INTERMEDIATE_PRE_SYNC

intermediate pre sync to parent thread

 

AGS_THREAD_INTERMEDIATE_POST_SYNC

intermediate post sync to parent thread

 

enum AgsThreadSyncFlags

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

Members

AGS_THREAD_WAIT_FOR_PARENT

wait for parent

 

AGS_THREAD_WAIT_FOR_SIBLING

wait for sibling

 

AGS_THREAD_WAIT_FOR_CHILDREN

wait for children

 

AGS_THREAD_WAIT_FOR_BARRIER

wait for barrier

 

AGS_THREAD_WAITING_FOR_PARENT

the thread is waiting for parent

 

AGS_THREAD_WAITING_FOR_SIBLING

the thread is waiting for sibling

 

AGS_THREAD_WAITING_FOR_CHILDREN

the thread is waiting for children

 

AGS_THREAD_WAITING_FOR_BARRIER

the thread is waiting for barrier

 

AGS_THREAD_BROADCAST_PARENT

broadcast parent

 

AGS_THREAD_BROADCAST_SIBLING

broadcast sibling

 

AGS_THREAD_BROADCAST_CHILDREN

broadcast children

 

AGS_THREAD_TREE_SYNC_0

exclusively synced tic group

 

AGS_THREAD_WAIT_0

wait tree to be synced

 

AGS_THREAD_TREE_SYNC_1

exclusively synced tic group

 

AGS_THREAD_WAIT_1

wait tree to be synced

 

AGS_THREAD_TREE_SYNC_2

exclusively synced tic group

 

AGS_THREAD_WAIT_2

wait tree to be synced

 

AGS_THREAD_TIMELOCK_RUN

run timelock

 

AGS_THREAD_TIMELOCK_WAIT

timelock wait

 

AGS_THREAD_TIMELOCK_RESUME

timelock resume

 

AGS_THREAD_SKIP_NON_GREEDY

skip non greedy

 

AGS_THREAD_SKIPPED_BY_TIMELOCK

thread was skipped by timelock

 

AGS_THREAD_LOCK_GREEDY_RUN_MUTEX

you shall lock run mutex of greedy locks

 

AGS_THREAD_START_SYNCED_FREQ

sync frequency as starting thread

 

AGS_THREAD_SYNCED_FREQ

the frequency was synced

 

AGS_THREAD_INTERRUPTED

the thread is interrupted

 

AGS_THREAD_MONITORING

the thread is monitoring interrupts

 

AGS_THREAD_WAIT_ASYNC_QUEUE

wait exclusive async running queue

 

AGS_THREAD_DONE_ASYNC_QUEUE

done exclusive async running queue

 

AGS_TYPE_THREAD

#define AGS_TYPE_THREAD                (ags_thread_get_type())

struct AgsThread

struct AgsThread;

struct AgsThreadClass

struct AgsThreadClass {
  GObjectClass object;

  guint (*clock)(AgsThread *thread);
  
  void (*start)(AgsThread *thread);
  void (*run)(AgsThread *thread);
  void (*suspend)(AgsThread *thread);
  void (*resume)(AgsThread *thread);
  void (*timelock)(AgsThread *thread);
  void (*stop)(AgsThread *thread);

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

Property Details

The “frequency” property

  “frequency”                gdouble

The frequency to run at in Hz.

Flags: Read / Write

Allowed values: [0.01,1000]

Default value: 250

Since: 1.0.0


The “max-precision” property

  “max-precision”            gdouble

The max-frequency to run at in Hz.

Flags: Read / Write

Allowed values: [0.01,1000]

Default value: 1000

Since: 1.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: 1.0.0


The “interrupted” signal

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

The ::interrupted() signal is invoked as thread should resume from interrupt.

Parameters

thread

the AgsThread

 

sig

the signal number

 

time_cycle

the cycles duration

 

time_spent

the time spent

 

user_data

user data set when the signal handler was connected.

 

Returns

the time spent

Flags: Run Last

Since: 1.0.0


The “resume” signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::resume() signal is invoked during resuming.

Parameters

thread

the AgsThread

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.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: 1.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: 1.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: 1.0.0


The “suspend” signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::suspend() signal is invoked during suspending.

Parameters

thread

the AgsThread

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.0.0


The “timelock” signal

void
user_function (AgsThread *thread,
               gpointer   user_data)

The ::timelock() signal is invoked as standard compution time exceeded.

Parameters

thread

the AgsThread

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.0.0