GI.Gst.Objects.BufferPool

A BufferPool is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties.

A BufferPool is created with bufferPoolNew.

Once a pool is created, it needs to be configured. A call to bufferPoolGetConfig returns the current configuration structure from the pool. With bufferPoolConfigSetParams and bufferPoolConfigSetAllocator the bufferpool parameters and allocator can be configured. Other properties can be configured in the pool depending on the pool implementation.

A bufferpool can have extra options that can be enabled with bufferPoolConfigAddOption. The available options can be retrieved with bufferPoolGetOptions. Some options allow for additional configuration properties to be set.

After the configuration structure has been configured, bufferPoolSetConfig updates the configuration in the pool. This can fail when the configuration structure is not accepted.

After the pool has been configured, it can be activated with bufferPoolSetActive. This will preallocate the configured resources in the pool.

When the pool is active, bufferPoolAcquireBuffer can be used to retrieve a buffer from the pool.

Buffers allocated from a bufferpool will automatically be returned to the pool with bufferPoolReleaseBuffer when their refcount drops to 0.

The bufferpool can be deactivated again with bufferPoolSetActive. All further bufferPoolAcquireBuffer calls will return an error. When all buffers are returned to the pool they will be freed.

Exported types

newtype BufferPool

Memory-managed wrapper type.

Constructors

BufferPool (ManagedPtr BufferPool)

Instances

Eq BufferPool

Defined in GI.Gst.Objects.BufferPool

Methods

(==) :: BufferPool -> BufferPool -> Bool

(/=) :: BufferPool -> BufferPool -> Bool

GObject BufferPool

Defined in GI.Gst.Objects.BufferPool

ManagedPtrNewtype BufferPool

Defined in GI.Gst.Objects.BufferPool

Methods

toManagedPtr :: BufferPool -> ManagedPtr BufferPool

TypedObject BufferPool

Defined in GI.Gst.Objects.BufferPool

Methods

glibType :: IO GType

HasParentTypes BufferPool

Defined in GI.Gst.Objects.BufferPool

IsGValue (Maybe BufferPool)

Convert BufferPool to and from GValue. See toGValue and fromGValue.

Defined in GI.Gst.Objects.BufferPool

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe BufferPool -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe BufferPool)

type ParentTypes BufferPool

Defined in GI.Gst.Objects.BufferPool

type ParentTypes BufferPool = '[Object, Object]

class (GObject o, IsDescendantOf BufferPool o) => IsBufferPool o

Type class for types which can be safely cast to BufferPool, for instance with toBufferPool.

Instances

(GObject o, IsDescendantOf BufferPool o) => IsBufferPool o

Defined in GI.Gst.Objects.BufferPool

toBufferPool :: (MonadIO m, IsBufferPool o) => o -> m BufferPool

Cast to BufferPool, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

acquireBuffer, addControlBinding, bindProperty, bindPropertyFull, defaultError, forceFloating, freezeNotify, getv, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, hasOption, isActive, isFloating, notify, notifyByPspec, ref, refSink, releaseBuffer, removeControlBinding, runDispose, stealData, stealQdata, suggestNextSync, syncValues, thawNotify, unparent, unref, watchClosure.

Getters

getConfig, getControlBinding, getControlRate, getData, getGValueArray, getName, getOptions, getParent, getPathString, getProperty, getQdata, getValue.

Setters

setActive, setConfig, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setData, setDataFull, setFlushing, setName, setParent, setProperty.

acquireBuffer

bufferPoolAcquireBuffer

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Maybe BufferPoolAcquireParams

params: parameters.

-> m (FlowReturn, Maybe Buffer)

Returns: a FlowReturn such as FlowReturnFlushing when the pool is inactive.

Acquires a buffer from pool. buffer should point to a memory location that can hold a pointer to the new buffer. When the pool is empty, this function will by default block until a buffer is released into the pool again or when the pool is set to flushing or deactivated.

params can contain optional parameters to influence the allocation.

configAddOption

bufferPoolConfigAddOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Text

option: an option to add

-> m ()

Enables the option in config. This will instruct the bufferpool to enable the specified option on the buffers that it allocates.

The options supported by pool can be retrieved with bufferPoolGetOptions.

configGetAllocator

bufferPoolConfigGetAllocator

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m (Bool, Maybe Allocator, AllocationParams)

Returns: True, if the values are set.

Gets the allocator and params from config.

configGetOption

bufferPoolConfigGetOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Word32

index: position in the option array to read

-> m (Maybe Text)

Returns: the option at index.

Parses an available config and gets the option at index of the options API array.

configGetParams

bufferPoolConfigGetParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m (Bool, Maybe Caps, Word32, Word32, Word32)

Returns: True if all parameters could be fetched.

Gets the configuration values from config.

configHasOption

bufferPoolConfigHasOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Text

option: an option

-> m Bool

Returns: True if the options array contains option.

Checks if config contains option.

configNOptions

bufferPoolConfigNOptions

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m Word32

Returns: the options array size as a guint.

Retrieves the number of values currently stored in the options array of the config structure.

configSetAllocator

bufferPoolConfigSetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsAllocator a)

=> Structure

config: a BufferPool configuration

-> Maybe a

allocator: a Allocator

-> Maybe AllocationParams

params: AllocationParams

-> m ()

Sets the allocator and params on config.

One of allocator and params can be Nothing, but not both. When allocator is Nothing, the default allocator of the pool will use the values in param to perform its allocation. When param is Nothing, the pool will use the provided allocator with its default AllocationParams.

A call to bufferPoolSetConfig can update the allocator and params with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in params. Use bufferPoolGetConfig to get the currently used values.

configSetParams

bufferPoolConfigSetParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Maybe Caps

caps: caps for the buffers

-> Word32

size: the size of each buffer, not including prefix and padding

-> Word32

minBuffers: the minimum amount of buffers to allocate.

-> Word32

maxBuffers: the maximum amount of buffers to allocate or 0 for unlimited.

-> m ()

Configures config with the given parameters.

configValidateParams

bufferPoolConfigValidateParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Maybe Caps

caps: the excepted caps of buffers

-> Word32

size: the expected size of each buffer, not including prefix and padding

-> Word32

minBuffers: the expected minimum amount of buffers to allocate.

-> Word32

maxBuffers: the expect maximum amount of buffers to allocate or 0 for unlimited.

-> m Bool

Returns: True, if the parameters are valid in this context.

Validates that changes made to config are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when bufferPoolSetConfig returns False. This expects that caps haven't changed and that minBuffers aren't lower then what we initially expected. This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding.

Since: 1.4

getConfig

bufferPoolGetConfig

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m Structure

Returns: a copy of the current configuration of pool.

Gets a copy of the current configuration of the pool. This configuration can be modified and used for the bufferPoolSetConfig call.

getOptions

bufferPoolGetOptions

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m [Text]

Returns: a Nothing terminated array of strings.

Gets a Nothing terminated array of string with supported bufferpool options for pool. An option would typically be enabled with bufferPoolConfigAddOption.

hasOption

bufferPoolHasOption

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Text

option: an option

-> m Bool

Returns: True if the buffer pool contains option.

Checks if the bufferpool supports option.

isActive

bufferPoolIsActive

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m Bool

Returns: True when the pool is active.

Checks if pool is active. A pool can be activated with the bufferPoolSetActive call.

new

bufferPoolNew

Arguments

:: (HasCallStack, MonadIO m)

=> m BufferPool

Returns: a new BufferPool instance

Creates a new BufferPool instance.

releaseBuffer

bufferPoolReleaseBuffer

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Buffer

buffer: a Buffer

-> m ()

Releases buffer to pool. buffer should have previously been allocated from pool with bufferPoolAcquireBuffer.

This function is usually called automatically when the last ref on buffer disappears.

setActive

bufferPoolSetActive

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Bool

active: the new active state

-> m Bool

Returns: False when the pool was not configured or when preallocation of the buffers failed.

Controls the active state of pool. When the pool is inactive, new calls to bufferPoolAcquireBuffer will return with FlowReturnFlushing.

Activating the bufferpool will preallocate all resources in the pool based on the configuration of the pool.

Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool.

setConfig

bufferPoolSetConfig

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Structure

config: a Structure

-> m Bool

Returns: True when the configuration could be set.

Sets the configuration of the pool. If the pool is already configured, and the configuration hasn't changed, this function will return True. If the pool is active, this method will return False and active configuration will remain. Buffers allocated from this pool must be returned or else this function will do nothing and return False.

config is a Structure that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with bufferPoolConfigSetParams, bufferPoolConfigSetAllocator and bufferPoolConfigAddOption.

If the parameters in config can not be set exactly, this function returns False and will try to update as much state as possible. The new state can then be retrieved and refined with bufferPoolGetConfig.

This function takes ownership of config.

setFlushing

bufferPoolSetFlushing

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Bool

flushing: whether to start or stop flushing

-> m ()

Enables or disables the flushing state of a pool without freeing or allocating buffers.

Since: 1.4