gi-glib-2.0.17: GLib bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.Thread

Contents

- Exported types
- Methods
  - errorQuark
  - exit
  - join
  - ref
  - self
  - unref
  - yield

Description

The `Thread` struct represents a running thread. This struct is returned by `g_thread_new()` or `g_thread_try_new()`. You can obtain the `Thread` struct representing the current thread by calling `threadSelf`.

GThread is refcounted, see `threadRef` and `threadUnref`. The thread represented by it holds a reference while it is running, and `threadJoin` consumes the reference that it is given, so it is normally not necessary to manage GThread references explicitly.

The structure is opaque -- none of its fields may be directly accessed.

Synopsis

- newtype Thread = Thread (ManagedPtr Thread)
- noThread :: Maybe Thread
- threadErrorQuark :: (HasCallStack, MonadIO m) => m Word32
- threadExit :: (HasCallStack, MonadIO m) => Ptr () -> m ()
- threadJoin :: (HasCallStack, MonadIO m) => Thread -> m (Ptr ())
- threadRef :: (HasCallStack, MonadIO m) => Thread -> m Thread
- threadSelf :: (HasCallStack, MonadIO m) => m Thread
- threadUnref :: (HasCallStack, MonadIO m) => Thread -> m ()
- threadYield :: (HasCallStack, MonadIO m) => m ()

# Exported types

newtype Thread Source #

Memory-managed wrapper type.

Constructors

Thread (ManagedPtr Thread) |

Instances

BoxedObject Thread Source # |
Instance details Defined in GI.GLib.Structs.Thread Methods boxedType :: Thread -> IO GType Source #

noThread :: Maybe Thread Source #

A convenience alias for `Nothing` :: `Maybe` `Thread`.

# Methods

## errorQuark

threadErrorQuark :: (HasCallStack, MonadIO m) => m Word32 Source #

No description available in the introspection data.

## exit

threadExit Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `retval`: the return value of this thread
-> m () |

Terminates the current thread.

If another thread is waiting for us using `threadJoin` then the waiting thread will be woken up and get `retval` as the return value of `threadJoin`.

Calling `threadExit` with a parameter `retval` is equivalent to returning `retval` from the function `func`, as given to `g_thread_new()`.

You must only call `threadExit` from a thread that you created yourself with `g_thread_new()` or related APIs. You must not call this function from a thread created with another threading library or or from within a `ThreadPool`.

## join

threadJoin Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Thread | `thread`: a `Thread`
-> m (Ptr ()) | Returns: the return value of the thread

Waits until `thread` finishes, i.e. the function `func`, as given to `g_thread_new()`, returns or `threadExit` is called. If `thread` has already terminated, then `threadJoin` returns immediately.

Any thread can wait for any other thread by calling `threadJoin`, not just its 'creator'. Calling `threadJoin` from multiple threads for the same `thread` leads to undefined behaviour.

The value returned by `func` or given to `threadExit` is returned by this function.

`threadJoin` consumes the reference to the passed-in `thread`. This will usually cause the `Thread` struct and associated resources to be freed. Use `threadRef` to obtain an extra reference if you want to keep the GThread alive beyond the `threadJoin` call.

## ref

threadRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Thread | `thread`: a `Thread`
-> m Thread | Returns: a new reference to `thread`

Increase the reference count on `thread`.

Since: 2.32

## self

threadSelf Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m Thread | Returns: the `Thread` representing the current thread

This function returns the `Thread` corresponding to the current thread. Note that this function does not increase the reference count of the returned struct.

This function will return a `Thread` even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as `threadJoin`) on these threads.

## unref

threadUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Thread | `thread`: a `Thread`
-> m () |

Decrease the reference count on `thread`, possibly freeing all resources associated with it.

Note that each thread holds a reference to its `Thread` while it is running, so it is safe to drop your own reference to it if you don't need it anymore.

Since: 2.32

## yield

threadYield :: (HasCallStack, MonadIO m) => m () Source #

Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run.

This function is often used as a method to make busy wait less evil.