Context#

Added in version 1.2.

class Context(**kwargs)#

Context is a container object used to store contexts like a device context, a display server connection and similar concepts that should be shared between multiple elements.

Applications can set a context on a complete pipeline by using set_context(), which will then be propagated to all child elements. Elements can handle these in ElementClass::set_context and merge them with the context information they already have.

When an element needs a context it will do the following actions in this order until one step succeeds:

  • Check if the element already has a context

  • Query downstream with CONTEXT for the context

  • Query upstream with CONTEXT for the context

  • Post a NEED_CONTEXT message on the bus with the required

    context types and afterwards check if a usable context was set now

  • Create a context by itself and post a HAVE_CONTEXT message

    on the bus.

Bins will catch NEED_CONTEXT messages and will set any previously known context on the element that asks for it if possible. Otherwise the application should provide one if it can.

Context can be persistent. A persistent Context is kept in elements when they reach NULL, non-persistent ones will be removed. Also, a non-persistent context won’t override a previous persistent context set to an element.

Constructors#

class Context
classmethod new(context_type: str, persistent: bool) → Context#

Creates a new context.

Added in version 1.2.

Parameters:

  • context_type – Context type

  • persistent – Persistent context

Methods#

class Context
get_context_type() → str#

Gets the type of context.

Added in version 1.2.

get_structure() → Structure#

Accesses the structure of the context.

Added in version 1.2.

get_task_pool() → tuple[bool, TaskPool | None]#

Gets the task pool from context.

Added in version 1.28.

has_context_type(context_type: str) → bool#

Checks if context has context_type.

Added in version 1.2.

Parameters:

context_type – Context type to check.

is_persistent() → bool#

Checks if context is persistent.

Added in version 1.2.

is_writable() → bool#

Tests if you can safely modify context. It is only safe to modify context when there is only one owner of the context - ie, the object is writable.

make_writable() → Context#

Returns a writable copy of context.

If there is only one reference count on context, the caller must be the owner, and so this function will return the context object unchanged. If on the other hand there is more than one reference on the object, a new context object will be returned. The caller’s reference on context will be removed, and instead the caller will own a reference to the returned object.

In short, this function unrefs the context in the argument and refs the context that it returns. Don’t access the argument after calling this function. See also: ref().

classmethod replace(old_context: Context, new_context: Context | None = None) → tuple[bool, Context]#

Modifies a pointer to a Context to point to a different Context. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old context is unreffed, the new one is reffed).

Either new_context or the Context pointed to by old_context may be None.

Added in version 1.2.

Parameters:

  • old_context – pointer to a pointer to a Context to be replaced.

  • new_context – pointer to a Context that will replace the context pointed to by old_context.

set_task_pool(pool: TaskPool | None = None) → None#

Sets pool on context as the task pool to be shared between elements. If pool is None, any previously set task pool will be removed from the context.

Added in version 1.28.

Parameters:

pool – a TaskPool or None to unset

writable_structure() → Structure#

Gets a writable version of the structure.

Added in version 1.2.