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 |
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.
Synopsis
- newtype BufferPool = BufferPool (ManagedPtr BufferPool)
- class (GObject o, IsDescendantOf BufferPool o) => IsBufferPool o
- toBufferPool :: (MonadIO m, IsBufferPool o) => o -> m BufferPool
- bufferPoolAcquireBuffer :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Maybe BufferPoolAcquireParams -> m (FlowReturn, Buffer)
- bufferPoolConfigAddOption :: (HasCallStack, MonadIO m) => Structure -> Text -> m ()
- bufferPoolConfigGetAllocator :: (HasCallStack, MonadIO m) => Structure -> m (Bool, Maybe Allocator, AllocationParams)
- bufferPoolConfigGetOption :: (HasCallStack, MonadIO m) => Structure -> Word32 -> m (Maybe Text)
- bufferPoolConfigGetParams :: (HasCallStack, MonadIO m) => Structure -> m (Bool, Maybe Caps, Word32, Word32, Word32)
- bufferPoolConfigHasOption :: (HasCallStack, MonadIO m) => Structure -> Text -> m Bool
- bufferPoolConfigNOptions :: (HasCallStack, MonadIO m) => Structure -> m Word32
- bufferPoolConfigSetAllocator :: (HasCallStack, MonadIO m, IsAllocator a) => Structure -> Maybe a -> Maybe AllocationParams -> m ()
- bufferPoolConfigSetParams :: (HasCallStack, MonadIO m) => Structure -> Maybe Caps -> Word32 -> Word32 -> Word32 -> m ()
- bufferPoolConfigValidateParams :: (HasCallStack, MonadIO m) => Structure -> Maybe Caps -> Word32 -> Word32 -> Word32 -> m Bool
- bufferPoolGetConfig :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> m Structure
- bufferPoolGetOptions :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> m [Text]
- bufferPoolHasOption :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Text -> m Bool
- bufferPoolIsActive :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> m Bool
- bufferPoolNew :: (HasCallStack, MonadIO m) => m BufferPool
- bufferPoolReleaseBuffer :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Buffer -> m ()
- bufferPoolSetActive :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Bool -> m Bool
- bufferPoolSetConfig :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Structure -> m Bool
- bufferPoolSetFlushing :: (HasCallStack, MonadIO m, IsBufferPool a) => a -> Bool -> m ()
Exported types
newtype BufferPool Source #
Memory-managed wrapper type.
BufferPool (ManagedPtr BufferPool) |
Instances
Eq BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool (==) :: BufferPool -> BufferPool -> Bool # (/=) :: BufferPool -> BufferPool -> Bool # | |
GObject BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool | |
ManagedPtrNewtype BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool toManagedPtr :: BufferPool -> ManagedPtr BufferPool | |
TypedObject BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool | |
HasParentTypes BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool | |
IsGValue (Maybe BufferPool) Source # | Convert |
Defined in GI.Gst.Objects.BufferPool gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe BufferPool -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe BufferPool) | |
type ParentTypes BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool |
class (GObject o, IsDescendantOf BufferPool o) => IsBufferPool o Source #
Type class for types which can be safely cast to BufferPool
, for instance with toBufferPool
.
Instances
(GObject o, IsDescendantOf BufferPool o) => IsBufferPool o Source # | |
Defined in GI.Gst.Objects.BufferPool |
toBufferPool :: (MonadIO m, IsBufferPool o) => o -> m BufferPool Source #
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 Source #
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Maybe BufferPoolAcquireParams |
|
-> m (FlowReturn, Buffer) | Returns: a |
Acquires a buffer from pool
. buffer
should point to a memory location that
can hold a pointer to the new buffer.
params
can contain optional parameters to influence the allocation.
configAddOption
bufferPoolConfigAddOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Text |
|
-> 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 Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m (Bool, Maybe Allocator, AllocationParams) | Returns: |
Gets the allocator
and params
from config
.
configGetOption
bufferPoolConfigGetOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Word32 |
|
-> m (Maybe Text) | Returns: the option at |
Parses an available config
and gets the option at index
of the options API
array.
configGetParams
bufferPoolConfigGetParams Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m (Bool, Maybe Caps, Word32, Word32, Word32) | Returns: |
Gets the configuration values from config
.
configHasOption
bufferPoolConfigHasOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Text |
|
-> m Bool | Returns: |
Checks if config
contains option
.
configNOptions
bufferPoolConfigNOptions Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m Word32 | Returns: the options array size as a |
Retrieves the number of values currently stored in the options array of the
config
structure.
configSetAllocator
bufferPoolConfigSetAllocator Source #
:: (HasCallStack, MonadIO m, IsAllocator a) | |
=> Structure |
|
-> Maybe a |
|
-> Maybe 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 Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Maybe Caps |
|
-> Word32 |
|
-> Word32 |
|
-> Word32 |
|
-> m () |
Configures config
with the given parameters.
configValidateParams
bufferPoolConfigValidateParams Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Maybe Caps |
|
-> Word32 |
|
-> Word32 |
|
-> Word32 |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> m Structure | Returns: a copy of the current configuration of |
Gets a copy of the current configuration of the pool. This configuration
can be modified and used for the bufferPoolSetConfig
call.
getOptions
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> m [Text] | Returns: a |
Gets a Nothing
terminated array of string with supported bufferpool options for
pool
. An option would typically be enabled with
bufferPoolConfigAddOption
.
hasOption
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Text |
|
-> m Bool | Returns: |
Checks if the bufferpool supports option
.
isActive
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> m Bool | Returns: |
Checks if pool
is active. A pool can be activated with the
bufferPoolSetActive
call.
new
:: (HasCallStack, MonadIO m) | |
=> m BufferPool | Returns: a new |
Creates a new BufferPool
instance.
releaseBuffer
bufferPoolReleaseBuffer Source #
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> 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
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Bool |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Structure |
|
-> m Bool | Returns: |
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 Source #
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Bool |
|
-> m () |
Enables or disables the flushing state of a pool
without freeing or
allocating buffers.
Since: 1.4