Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
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 a 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.
Use objectUnref
to release the reference to a bufferpool. If the
refcount of the pool reaches 0, the pool 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
- noBufferPool :: Maybe 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, Allocator, AllocationParams)
- bufferPoolConfigGetOption :: (HasCallStack, MonadIO m) => Structure -> Word32 -> m Text
- bufferPoolConfigGetParams :: (HasCallStack, MonadIO m) => Structure -> m (Bool, 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 -> Caps -> Word32 -> Word32 -> Word32 -> m ()
- bufferPoolConfigValidateParams :: (HasCallStack, MonadIO m) => Structure -> 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.
Instances
GObject BufferPool Source # | |
Defined in GI.Gst.Objects.BufferPool gobjectType :: IO GType # | |
HasParentTypes BufferPool Source # | |
Defined in GI.Gst.Objects.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
.
noBufferPool :: Maybe BufferPool Source #
A convenience alias for Nothing
:: Maybe
BufferPool
.
Methods
acquireBuffer
bufferPoolAcquireBuffer Source #
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> Maybe BufferPoolAcquireParams |
|
-> m (FlowReturn, Buffer) | Returns: a |
Acquire a buffer from pool
. buffer
should point to a memory location that
can hold a pointer to the new buffer.
params
can be Nothing
or contain optional parameters to influence the
allocation.
configAddOption
bufferPoolConfigAddOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Text |
|
-> m () |
Enabled the option in config
. This will instruct the bufferpool
to enable
the specified option on the buffers that it allocates.
The supported options by pool
can be retrieved with bufferPoolGetOptions
.
configGetAllocator
bufferPoolConfigGetAllocator Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m (Bool, Allocator, AllocationParams) | Returns: |
Get the allocator
and params
from config
.
configGetOption
bufferPoolConfigGetOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Word32 |
|
-> m Text | Returns: a |
Parse an available config
and get the option at index
of the options API
array.
configGetParams
bufferPoolConfigGetParams Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m (Bool, Caps, Word32, Word32, Word32) | Returns: |
Get the configuration values from config
.
configHasOption
bufferPoolConfigHasOption Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Text |
|
-> m Bool | Returns: |
Check if config
contains option
.
configNOptions
bufferPoolConfigNOptions Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> m Word32 | Returns: the options array size as a |
Retrieve 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 () |
Set 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 |
|
-> Caps |
|
-> Word32 |
|
-> Word32 |
|
-> Word32 |
|
-> m () |
Configure config
with the given parameters.
configValidateParams
bufferPoolConfigValidateParams Source #
:: (HasCallStack, MonadIO m) | |
=> Structure |
|
-> Caps |
|
-> Word32 |
|
-> Word32 |
|
-> Word32 |
|
-> m Bool | Returns: |
Validate 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 |
Get a copy of the current configuration of the pool. This configuration
can either be modified and used for the bufferPoolSetConfig
call
or it must be freed after usage.
getOptions
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> m [Text] | Returns: a |
Get 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: |
Check if the bufferpool supports option
.
isActive
:: (HasCallStack, MonadIO m, IsBufferPool a) | |
=> a |
|
-> m Bool | Returns: |
Check 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 () |
Release 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: |
Control 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: |
Set the configuration of the pool. If the pool is already configured, and
the configuration haven't change, this function will return True
. If the
pool is active, this method will return False
and active configuration
will remain. Buffers allocated form 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 () |
Enable or disable the flushing state of a pool
without freeing or
allocating buffers.
Since: 1.4