Class Promise

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Promise
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Promise extends ProxyInstance

The GstPromise 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 GstPromise is created with gst_promise_new() by the consumer and passed to the producer to avoid thread safety issues with the change callback. A GstPromise can be replied to with a value (or an error) by the producer with gst_promise_reply(). The exact value returned is defined by the API contract of the producer and null may be a valid reply. 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 GSTPROMISERESULTEXPIRED state set by a call to 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 GstBus. A callback can also be installed at GstPromise creation for result changes with gst_promise_new_with_change_func(). The change callback can be used to chain GstPromises's together as in the following example.

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 GstPromise starts out with a GstPromiseResult of PromiseResult.PENDING and only ever transitions once into one of the other GstPromiseResult's.

In order to support multi-threaded code, gst_promise_reply(), gst_promise_interrupt() and 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:

  1. That gst_promise_reply() and gst_promise_interrupt() cannot be called after gst_promise_expire()
  2. That gst_promise_reply() and gst_promise_interrupt() cannot be called twice.

The change function set with gst_promise_new_with_change_func() is called directly from either the gst_promise_reply(), gst_promise_interrupt() or gst_promise_expire() and can be called from an arbitrary thread. GstPromise using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses GstPromise.

Since:
1.14

  • Constructor Details

    • Promise

      public Promise(MemorySegment address)
      Create a Promise proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Promise

      public Promise()

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Promise class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readParent

      public @Nullable MiniObject readParent()
      Read the value of the field parent.
      Returns:
      The value of the field parent

    • writeParent

      public void writeParent(@Nullable MiniObject parent)
      Write a value in the field parent.
      Parameters:
      parent - The new value for the field parent

    • withChangeFunc

      public static Promise withChangeFunc(@Nullable PromiseChangeFunc func)
      func will be called exactly once when transitioning out of PromiseResult.PENDING into any of the other GstPromiseResult states.
      Parameters:
      func - a GstPromiseChangeFunc to call
      Returns:
      a new GstPromise
      Since:
      1.14

    • expire

      public void expire()
      Expire a promise. This will wake up any waiters with PromiseResult.EXPIRED. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).
      Since:
      1.14

    • getReply

      public @Nullable Structure getReply()
      Retrieve the reply set on promise. this Promise must be in PromiseResult.REPLIED and the returned structure is owned by this Promise
      Returns:
      The reply set on this Promise
      Since:
      1.14

    • interrupt

      public void interrupt()
      Interrupt waiting for a promise. This will wake up any waiters with PromiseResult.INTERRUPTED. Called when the consumer does not want the value produced anymore.
      Since:
      1.14

    • ref

      public Promise ref()
      Increases the refcount of the given this Promise by one.
      Returns:
      this Promise
      Since:
      1.14

    • reply

      public void reply(@Nullable Structure s)

      Set a reply on promise. This will wake up any waiters with PromiseResult.REPLIED. Called by the producer of the value to indicate success (or failure).

      If this Promise has already been interrupted by the consumer, then this reply is not visible to the consumer.

      Parameters:
      s - a GstStructure with the the reply contents
      Since:
      1.14

    • unref

      public void unref()
      Decreases the refcount of the promise. If the refcount reaches 0, the promise will be freed.
      Since:
      1.14

    • wait_

      public PromiseResult wait_()
      Wait for this Promise to move out of the PromiseResult.PENDING state. If this Promise is not in PromiseResult.PENDING then it will return immediately with the current result.
      Returns:
      the result of the promise
      Since:
      1.14