gi-glib-2.0.30: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.GLib.Structs.AsyncQueue

Contents

- Exported types
- Methods
  - length
  - lengthUnlocked
  - lock
  - new
  - newFull
  - pop
  - popUnlocked
  - push
  - pushFront
  - pushFrontUnlocked
  - pushSorted
  - pushSortedUnlocked
  - pushUnlocked
  - ref
  - refUnlocked
  - remove
  - removeUnlocked
  - sort
  - sortUnlocked
  - timedPop
  - timedPopUnlocked
  - timeoutPop
  - timeoutPopUnlocked
  - tryPop
  - tryPopUnlocked
  - unlock
  - unrefAndUnlock

Description

An opaque data structure which represents an asynchronous queue.

It should only be accessed through the `g_async_queue_*` functions.

Synopsis

- newtype AsyncQueue = AsyncQueue (ManagedPtr AsyncQueue)
- asyncQueueLength :: (HasCallStack, MonadIO m) => AsyncQueue -> m Int32
- asyncQueueLengthUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> m Int32
- asyncQueueLock :: (HasCallStack, MonadIO m) => AsyncQueue -> m ()
- asyncQueueNew :: (HasCallStack, MonadIO m) => m AsyncQueue
- asyncQueueNewFull :: (HasCallStack, MonadIO m) => Maybe DestroyNotify -> m AsyncQueue
- asyncQueuePop :: (HasCallStack, MonadIO m) => AsyncQueue -> m (Ptr ())
- asyncQueuePopUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> m (Ptr ())
- asyncQueuePush :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m ()
- asyncQueuePushFront :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m ()
- asyncQueuePushFrontUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m ()
- asyncQueuePushSorted :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> CompareDataFunc -> m ()
- asyncQueuePushSortedUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> CompareDataFunc -> m ()
- asyncQueuePushUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m ()
- asyncQueueRef :: (HasCallStack, MonadIO m) => AsyncQueue -> m AsyncQueue
- asyncQueueRefUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> m ()
- asyncQueueRemove :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m Bool
- asyncQueueRemoveUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> Ptr () -> m Bool
- asyncQueueSort :: (HasCallStack, MonadIO m) => AsyncQueue -> CompareDataFunc -> m ()
- asyncQueueSortUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> CompareDataFunc -> m ()
- asyncQueueTimedPop :: (HasCallStack, MonadIO m) => AsyncQueue -> TimeVal -> m (Ptr ())
- asyncQueueTimedPopUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> TimeVal -> m (Ptr ())
- asyncQueueTimeoutPop :: (HasCallStack, MonadIO m) => AsyncQueue -> Word64 -> m (Ptr ())
- asyncQueueTimeoutPopUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> Word64 -> m (Ptr ())
- asyncQueueTryPop :: (HasCallStack, MonadIO m) => AsyncQueue -> m (Ptr ())
- asyncQueueTryPopUnlocked :: (HasCallStack, MonadIO m) => AsyncQueue -> m (Ptr ())
- asyncQueueUnlock :: (HasCallStack, MonadIO m) => AsyncQueue -> m ()
- asyncQueueUnrefAndUnlock :: (HasCallStack, MonadIO m) => AsyncQueue -> m ()

# Exported types

newtype AsyncQueue Source #

Memory-managed wrapper type.

Constructors

AsyncQueue (ManagedPtr AsyncQueue) |

#### Instances

Instances details

Eq AsyncQueue Source # |
Instance details Defined in GI.GLib.Structs.AsyncQueue Methods (==) :: AsyncQueue -> AsyncQueue -> Bool Source # (/=) :: AsyncQueue -> AsyncQueue -> Bool Source #
BoxedPtr AsyncQueue Source # |
Instance details Defined in GI.GLib.Structs.AsyncQueue Methods boxedPtrCopy :: AsyncQueue -> IO AsyncQueue Source # boxedPtrFree :: AsyncQueue -> IO () Source #
ManagedPtrNewtype AsyncQueue Source # |
Instance details Defined in GI.GLib.Structs.AsyncQueue Methods toManagedPtr :: AsyncQueue -> ManagedPtr AsyncQueue Source #

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

length, lengthUnlocked, lock, pop, popUnlocked, push, pushFront, pushFrontUnlocked, pushSorted, pushSortedUnlocked, pushUnlocked, ref, refUnlocked, remove, removeUnlocked, sort, sortUnlocked, timedPop, timedPopUnlocked, timeoutPop, timeoutPopUnlocked, tryPop, tryPopUnlocked, unlock, unrefAndUnlock.

#### Getters

None.

#### Setters

None.

## length

asyncQueueLength Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`.
-> m Int32 | Returns: the length of the `queue`

Returns the length of the queue.

Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the `queue`. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling.

## lengthUnlocked

asyncQueueLengthUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m Int32 | Returns: the length of the `queue`.

Returns the length of the queue.

Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the `queue`. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling.

This function must be called while holding the `queue`'s lock.

## lock

asyncQueueLock Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m () |

Acquires the `queue`'s lock. If another thread is already holding the lock, this call will block until the lock becomes available.

Call `asyncQueueUnlock` to drop the lock again.

While holding the lock, you can only call the g_async_queue_*`_unlocked()` functions on `queue`. Otherwise, deadlock may occur.

## new

asyncQueueNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m AsyncQueue | Returns: a new `AsyncQueue`. Free with `asyncQueueUnref`

Creates a new asynchronous queue.

## newFull

asyncQueueNewFull Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe DestroyNotify | `itemFreeFunc`: function to free queue elements
-> m AsyncQueue | Returns: a new `AsyncQueue`. Free with `asyncQueueUnref`

Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref.

Since: 2.16

## pop

asyncQueuePop Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m (Ptr ()) | Returns: data from the queue

Pops data from the `queue`. If `queue` is empty, this function blocks until data becomes available.

## popUnlocked

asyncQueuePopUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m (Ptr ()) | Returns: data from the queue.

Pops data from the `queue`. If `queue` is empty, this function blocks until data becomes available.

This function must be called while holding the `queue`'s lock.

## push

asyncQueuePush Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `data`: data to push onto the `queue`
-> m () |

Pushes the `data` into the `queue`.

The `data` parameter must not be `Nothing`.

## pushFront

asyncQueuePushFront Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `item`: data to push into the `queue`
-> m () |

Pushes the `item` into the `queue`. `item` must not be `Nothing`. In contrast to `asyncQueuePush`, this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.

Since: 2.46

## pushFrontUnlocked

asyncQueuePushFrontUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `item`: data to push into the `queue`
-> m () |

Pushes the `item` into the `queue`. `item` must not be `Nothing`. In contrast to `asyncQueuePushUnlocked`, this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.

This function must be called while holding the `queue`'s lock.

Since: 2.46

## pushSorted

asyncQueuePushSorted Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `data`: the `data` to push into the `queue`
-> CompareDataFunc | `func`: the `CompareDataFunc` is used to sort `queue`
-> m () |

Inserts `data` into `queue` using `func` to determine the new position.

This function requires that the `queue` is sorted before pushing on new elements, see `asyncQueueSort`.

This function will lock `queue` before it sorts the queue and unlock it when it is finished.

For an example of `func` see `asyncQueueSort`.

Since: 2.10

## pushSortedUnlocked

asyncQueuePushSortedUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `data`: the data to push into the `queue`
-> CompareDataFunc | `func`: the `CompareDataFunc` is used to sort `queue`
-> m () |

Inserts `data` into `queue` using `func` to determine the new position.

The sort function `func` is passed two elements of the `queue`. It should return 0 if they are equal, a negative value if the first element should be higher in the `queue` or a positive value if the first element should be lower in the `queue` than the second element.

This function requires that the `queue` is sorted before pushing on new elements, see `asyncQueueSort`.

This function must be called while holding the `queue`'s lock.

For an example of `func` see `asyncQueueSort`.

Since: 2.10

## pushUnlocked

asyncQueuePushUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `data`: data to push onto the `queue`
-> m () |

Pushes the `data` into the `queue`.

The `data` parameter must not be `Nothing`.

This function must be called while holding the `queue`'s lock.

## ref

asyncQueueRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m AsyncQueue | Returns: the `queue` that was passed in (since 2.6)

Increases the reference count of the asynchronous `queue` by 1. You do not need to hold the lock to call this function.

## refUnlocked

asyncQueueRefUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m () |

Deprecated: (Since version 2.8)Reference counting is done atomically.so `asyncQueueRef` can be used regardless of the `queue`'slock.

Increases the reference count of the asynchronous `queue` by 1.

## remove

asyncQueueRemove Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `item`: the data to remove from the `queue`
-> m Bool | Returns: `True` if the item was removed

Remove an item from the queue.

Since: 2.46

## removeUnlocked

asyncQueueRemoveUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Ptr () | `item`: the data to remove from the `queue`
-> m Bool | Returns: `True` if the item was removed

Remove an item from the queue.

This function must be called while holding the `queue`'s lock.

Since: 2.46

## sort

asyncQueueSort Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> CompareDataFunc | `func`: the `CompareDataFunc` is used to sort `queue`
-> m () |

Sorts `queue` using `func`.

The sort function `func` is passed two elements of the `queue`. It should return 0 if they are equal, a negative value if the first element should be higher in the `queue` or a positive value if the first element should be lower in the `queue` than the second element.

This function will lock `queue` before it sorts the queue and unlock it when it is finished.

If you were sorting a list of priority numbers to make sure the lowest priority would be at the top of the queue, you could use:

### C code

    gint32 id1;
    gint32 id2;

    id1 = GPOINTER_TO_INT (element1);
    id2 = GPOINTER_TO_INT (element2);

    return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);

Since: 2.10

## sortUnlocked

asyncQueueSortUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> CompareDataFunc | `func`: the `CompareDataFunc` is used to sort `queue`
-> m () |

Sorts `queue` using `func`.

The sort function `func` is passed two elements of the `queue`. It should return 0 if they are equal, a negative value if the first element should be higher in the `queue` or a positive value if the first element should be lower in the `queue` than the second element.

This function must be called while holding the `queue`'s lock.

Since: 2.10

## timedPop

asyncQueueTimedPop Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> TimeVal | `endTime`: a `TimeVal`, determining the final time
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is received before `endTime`.

Deprecated: use `asyncQueueTimeoutPop`.

Pops data from the `queue`. If the queue is empty, blocks until `endTime` or until data becomes available.

If no data is received before `endTime`, `Nothing` is returned.

To easily calculate `endTime`, a combination of `getRealTime` and `timeValAdd` can be used.

## timedPopUnlocked

asyncQueueTimedPopUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> TimeVal | `endTime`: a `TimeVal`, determining the final time
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is received before `endTime`.

Deprecated: use `asyncQueueTimeoutPopUnlocked`.

Pops data from the `queue`. If the queue is empty, blocks until `endTime` or until data becomes available.

If no data is received before `endTime`, `Nothing` is returned.

To easily calculate `endTime`, a combination of `getRealTime` and `timeValAdd` can be used.

This function must be called while holding the `queue`'s lock.

## timeoutPop

asyncQueueTimeoutPop Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Word64 | `timeout`: the number of microseconds to wait
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is received before the timeout.

Pops data from the `queue`. If the queue is empty, blocks for `timeout` microseconds, or until data becomes available.

If no data is received before the timeout, `Nothing` is returned.

## timeoutPopUnlocked

asyncQueueTimeoutPopUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> Word64 | `timeout`: the number of microseconds to wait
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is received before the timeout.

Pops data from the `queue`. If the queue is empty, blocks for `timeout` microseconds, or until data becomes available.

If no data is received before the timeout, `Nothing` is returned.

This function must be called while holding the `queue`'s lock.

## tryPop

asyncQueueTryPop Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is available immediately.

Tries to pop data from the `queue`. If no data is available, `Nothing` is returned.

## tryPopUnlocked

asyncQueueTryPopUnlocked Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m (Ptr ()) | Returns: data from the queue or `Nothing`, when no data is available immediately.

Tries to pop data from the `queue`. If no data is available, `Nothing` is returned.

This function must be called while holding the `queue`'s lock.

## unlock

asyncQueueUnlock Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m () |

Releases the queue's lock.

Calling this function when you have not acquired the with `asyncQueueLock` leads to undefined behaviour.

## unrefAndUnlock

asyncQueueUnrefAndUnlock Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AsyncQueue | `queue`: a `AsyncQueue`
-> m () |

Deprecated: (Since version 2.8)Reference counting is done atomically.so `asyncQueueUnref` can be used regardless of the `queue`'slock.

Decreases the reference count of the asynchronous `queue` by 1 and releases the lock. This function must be called while holding the `queue`'s lock. If the reference count went to 0, the `queue` will be destroyed and the memory allocated will be freed.