:right-sidebar: True Promise =================================================================== .. currentmodule:: gi.repository.Gst .. versionadded:: 1.14 .. class:: Promise(**kwargs) :no-contents-entry: The :obj:`~gi.repository.Gst.Promise` object implements the container for values that may be available later. i.e. a Future or a Promise in `https://en.wikipedia.org/wiki/Futures_and_promises `__\. As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value. A :obj:`~gi.repository.Gst.Promise` is created with :func:`~gi.repository.Gst.Promise.new` by the consumer and passed to the producer to avoid thread safety issues with the change callback. A :obj:`~gi.repository.Gst.Promise` can be replied to with a value (or an error) by the producer with :func:`~gi.repository.Gst.Promise.reply`. The exact value returned is defined by the API contract of the producer and :const:`None` may be a valid reply. :func:`~gi.repository.Gst.Promise.interrupt` is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The ``GST_PROMISE_RESULT_EXPIRED`` state set by a call to :func:`~gi.repository.Gst.Promise.expire` indicates to the consumer that a value will never be produced and is intended to be called by a third party that implements some notion of message handling such as :obj:`~gi.repository.Gst.Bus`\. A callback can also be installed at :obj:`~gi.repository.Gst.Promise` creation for result changes with :func:`~gi.repository.Gst.Promise.new_with_change_func`. The change callback can be used to chain :obj:`~gi.repository.Gst.Promise`\'s together as in the following example. .. code-block:: C :dedent: const GstStructure *reply; GstPromise *p; if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) return; // interrupted or expired value reply = gst_promise_get_reply (promise); if (error in reply) return; // propagate error p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); pass p to promise-using API Each :obj:`~gi.repository.Gst.Promise` starts out with a :obj:`~gi.repository.Gst.PromiseResult` of :const:`~gi.repository.Gst.PromiseResult.PENDING` and only ever transitions once into one of the other :obj:`~gi.repository.Gst.PromiseResult`\'s. In order to support multi-threaded code, :func:`~gi.repository.Gst.Promise.reply`, :func:`~gi.repository.Gst.Promise.interrupt` and :func:`~gi.repository.Gst.Promise.expire` may all be from different threads with some restrictions and the final result of the promise is whichever call is made first. There are two restrictions on ordering: - That :func:`~gi.repository.Gst.Promise.reply` and :func:`~gi.repository.Gst.Promise.interrupt` cannot be called after :func:`~gi.repository.Gst.Promise.expire` - That :func:`~gi.repository.Gst.Promise.reply` and :func:`~gi.repository.Gst.Promise.interrupt` cannot be called twice. The change function set with :func:`~gi.repository.Gst.Promise.new_with_change_func` is called directly from either the :func:`~gi.repository.Gst.Promise.reply`, :func:`~gi.repository.Gst.Promise.interrupt` or :func:`~gi.repository.Gst.Promise.expire` and can be called from an arbitrary thread. :obj:`~gi.repository.Gst.Promise` using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses :obj:`~gi.repository.Gst.Promise`\. Constructors ------------ .. rst-class:: interim-class .. class:: Promise :no-index: .. classmethod:: new() -> ~gi.repository.Gst.Promise .. versionadded:: 1.14 .. classmethod:: new_with_change_func(func: ~typing.Callable[[~gi.repository.Gst.Promise, ~typing.Any], None], user_data: ~typing.Any = None) -> ~gi.repository.Gst.Promise ``func`` will be called exactly once when transitioning out of :const:`~gi.repository.Gst.PromiseResult.PENDING` into any of the other :obj:`~gi.repository.Gst.PromiseResult` states. .. versionadded:: 1.14 :param func: a :obj:`~gi.repository.Gst.PromiseChangeFunc` to call :param user_data: argument to call ``func`` with Methods ------- .. rst-class:: interim-class .. class:: Promise :no-index: .. method:: expire() -> None Expire a ``promise``\. This will wake up any waiters with :const:`~gi.repository.Gst.PromiseResult.EXPIRED`. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered). .. versionadded:: 1.14 .. method:: get_reply() -> ~gi.repository.Gst.Structure | None Retrieve the reply set on ``promise``\. ``promise`` must be in :const:`~gi.repository.Gst.PromiseResult.REPLIED` and the returned structure is owned by ``promise`` .. versionadded:: 1.14 .. method:: interrupt() -> None Interrupt waiting for a ``promise``\. This will wake up any waiters with :const:`~gi.repository.Gst.PromiseResult.INTERRUPTED`. Called when the consumer does not want the value produced anymore. .. versionadded:: 1.14 .. method:: reply(s: ~gi.repository.Gst.Structure | None = None) -> None Set a reply on ``promise``\. This will wake up any waiters with :const:`~gi.repository.Gst.PromiseResult.REPLIED`. Called by the producer of the value to indicate success (or failure). If ``promise`` has already been interrupted by the consumer, then this reply is not visible to the consumer. .. versionadded:: 1.14 :param s: a :obj:`~gi.repository.Gst.Structure` with the the reply contents .. method:: wait() -> ~gi.repository.Gst.PromiseResult Wait for ``promise`` to move out of the :const:`~gi.repository.Gst.PromiseResult.PENDING` state. If ``promise`` is not in :const:`~gi.repository.Gst.PromiseResult.PENDING` then it will return immediately with the current result. .. versionadded:: 1.14 Fields ------ .. rst-class:: interim-class .. class:: Promise :no-index: .. attribute:: parent Parent :obj:`~gi.repository.Gst.MiniObject`