Class Poll

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

A GstPoll keeps track of file descriptors much like fd_set (used with select ()) or a struct pollfd array (used with poll ()). Once created with gst_poll_new(), the set can be used to wait for file descriptors to be readable and/or writable. It is possible to make this wait be controlled by specifying true for the controllable flag when creating the set (or later calling gst_poll_set_controllable()).

New file descriptors are added to the set using gst_poll_add_fd(), and removed using gst_poll_remove_fd(). Controlling which file descriptors should be waited for to become readable and/or writable are done using gst_poll_fd_ctl_read(), gst_poll_fd_ctl_write() and gst_poll_fd_ctl_pri().

Use gst_poll_wait() to wait for the file descriptors to actually become readable and/or writable, or to timeout if no file descriptor is available in time. The wait can be controlled by calling gst_poll_restart() and gst_poll_set_flushing().

Once the file descriptor set has been waited for, one can use gst_poll_fd_has_closed() to see if the file descriptor has been closed, gst_poll_fd_has_error() to see if it has generated an error, gst_poll_fd_can_read() to see if it is possible to read from the file descriptor, and gst_poll_fd_can_write() to see if it is possible to write to it.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Poll(MemorySegment address)
    Create a Poll proxy instance for the provided memory address.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addFd(PollFD fd)
    Add a file descriptor to the file descriptor set.
    boolean
    fdCanRead(PollFD fd)
    Check if fd in this Poll has data to be read.
    boolean
    fdCanWrite(PollFD fd)
    Check if fd in this Poll can be used for writing.
    boolean
    fdCtlPri(PollFD fd, boolean active)
    Control whether the descriptor fd in this Poll will be monitored for exceptional conditions (POLLPRI).
    boolean
    fdCtlRead(PollFD fd, boolean active)
    Control whether the descriptor fd in this Poll will be monitored for readability.
    boolean
    fdCtlWrite(PollFD fd, boolean active)
    Control whether the descriptor fd in this Poll will be monitored for writability.
    boolean
    fdHasClosed(PollFD fd)
    Check if fd in this Poll has closed the connection.
    boolean
    fdHasError(PollFD fd)
    Check if fd in this Poll has an error.
    boolean
    fdHasPri(PollFD fd)
    Check if fd in this Poll has an exceptional condition (POLLPRI).
    void
    fdIgnored(PollFD fd)
    Mark fd as ignored so that the next call to gst_poll_wait() will yield the same result for fd as last time.
    void
    free()
    Free a file descriptor set.
    static MemoryLayout
    getMemoryLayout()
    The memory layout of the native struct.
    void
    getReadGpollfd(PollFD fd)
    Get a GPollFD for the reading part of the control socket.
    static @Nullable Poll
    new_(boolean controllable)
    Create a new file descriptor set.
    static @Nullable Poll
    newTimer()
    Create a new poll object that can be used for scheduling cancellable timeouts.
    boolean
    readControl()
    Read a byte from the control socket of the controllable set.
    boolean
    removeFd(PollFD fd)
    Remove a file descriptor from the file descriptor set.
    void
    restart()
    Restart any gst_poll_wait() that is in progress.
    boolean
    setControllable(boolean controllable)
    When controllable is true, this function ensures that future calls to gst_poll_wait() will be affected by gst_poll_restart() and gst_poll_set_flushing().
    void
    setFlushing(boolean flushing)
    When flushing is true, this function ensures that current and future calls to gst_poll_wait() will return -1, with errno set to EBUSY.
    int
    wait_(ClockTime timeout)
    Wait for activity on the file descriptors in set. This function waits up to the specified timeout. A timeout of GST_CLOCK_TIME_NONE waits forever.
    boolean
    writeControl()
    Write a byte to the control socket of the controllable set. This function is mostly useful for timer GstPoll objects created with gst_poll_new_timer().

    Methods inherited from class ProxyInstance

    equals, handle, hashCode

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Poll

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

  • Method Details

    • getMemoryLayout

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

    • new_

      public static @Nullable Poll new_(boolean controllable)

      Create a new file descriptor set. If controllable, it is possible to restart or flush a call to gst_poll_wait() with gst_poll_restart() and gst_poll_set_flushing() respectively.

      Free-function: gst_poll_free

      Parameters:
      controllable - whether it should be possible to control a wait.
      Returns:
      a new GstPoll, or null in case of an error. Free with gst_poll_free().

    • newTimer

      public static @Nullable Poll newTimer()

      Create a new poll object that can be used for scheduling cancellable timeouts.

      A timeout is performed with gst_poll_wait(). Multiple timeouts can be performed from different threads.

      Free-function: gst_poll_free

      Returns:
      a new GstPoll, or null in case of an error. Free with gst_poll_free().

    • addFd

      public boolean addFd(PollFD fd)
      Add a file descriptor to the file descriptor set.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the file descriptor was successfully added to the set.

    • fdCanRead

      public boolean fdCanRead(PollFD fd)
      Check if fd in this Poll has data to be read.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the descriptor has data to be read.

    • fdCanWrite

      public boolean fdCanWrite(PollFD fd)
      Check if fd in this Poll can be used for writing.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the descriptor can be used for writing.

    • fdCtlPri

      public boolean fdCtlPri(PollFD fd, boolean active)

      Control whether the descriptor fd in this Poll will be monitored for exceptional conditions (POLLPRI).

      Not implemented on Windows (will just return false there).

      Parameters:
      fd - a file descriptor.
      active - a new status.
      Returns:
      true if the descriptor was successfully updated.
      Since:
      1.16

    • fdCtlRead

      public boolean fdCtlRead(PollFD fd, boolean active)
      Control whether the descriptor fd in this Poll will be monitored for readability.
      Parameters:
      fd - a file descriptor.
      active - a new status.
      Returns:
      true if the descriptor was successfully updated.

    • fdCtlWrite

      public boolean fdCtlWrite(PollFD fd, boolean active)
      Control whether the descriptor fd in this Poll will be monitored for writability.
      Parameters:
      fd - a file descriptor.
      active - a new status.
      Returns:
      true if the descriptor was successfully updated.

    • fdHasClosed

      public boolean fdHasClosed(PollFD fd)
      Check if fd in this Poll has closed the connection.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the connection was closed.

    • fdHasError

      public boolean fdHasError(PollFD fd)
      Check if fd in this Poll has an error.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the descriptor has an error.

    • fdHasPri

      public boolean fdHasPri(PollFD fd)

      Check if fd in this Poll has an exceptional condition (POLLPRI).

      Not implemented on Windows (will just return false there).

      Parameters:
      fd - a file descriptor.
      Returns:
      true if the descriptor has an exceptional condition.
      Since:
      1.16

    • fdIgnored

      public void fdIgnored(PollFD fd)

      Mark fd as ignored so that the next call to gst_poll_wait() will yield the same result for fd as last time. This function must be called if no operation (read/write/recv/send/etc.) will be performed on fd before the next call to gst_poll_wait().

      The reason why this is needed is because the underlying implementation might not allow querying the fd more than once between calls to one of the re-enabling operations.

      Parameters:
      fd - a file descriptor.

    • free

      public void free()
      Free a file descriptor set.

    • getReadGpollfd

      public void getReadGpollfd(PollFD fd)
      Get a GPollFD for the reading part of the control socket. This is useful when integrating with a GSource and GMainLoop.
      Parameters:
      fd - a GPollFD

    • readControl

      public boolean readControl()

      Read a byte from the control socket of the controllable set.

      This function only works for timer GstPoll objects created with gst_poll_new_timer().

      Returns:
      true on success. false when when there was no byte to read or reading the byte failed. If there was no byte to read, and only then, errno will contain EWOULDBLOCK or EAGAIN. For all other values of errno this always signals a critical error.

    • removeFd

      public boolean removeFd(PollFD fd)
      Remove a file descriptor from the file descriptor set.
      Parameters:
      fd - a file descriptor.
      Returns:
      true if the file descriptor was successfully removed from the set.

    • restart

      public void restart()

      Restart any gst_poll_wait() that is in progress. This function is typically used after adding or removing descriptors to set.

      If this Poll is not controllable, then this call will have no effect.

      This function only works for non-timer GstPoll objects created with gst_poll_new().

    • setControllable

      public boolean setControllable(boolean controllable)

      When controllable is true, this function ensures that future calls to gst_poll_wait() will be affected by gst_poll_restart() and gst_poll_set_flushing().

      This function only works for non-timer GstPoll objects created with gst_poll_new().

      Parameters:
      controllable - new controllable state.
      Returns:
      true if the controllability of this Poll could be updated.

    • setFlushing

      public void setFlushing(boolean flushing)

      When flushing is true, this function ensures that current and future calls to gst_poll_wait() will return -1, with errno set to EBUSY.

      Unsetting the flushing state will restore normal operation of set.

      This function only works for non-timer GstPoll objects created with gst_poll_new().

      Parameters:
      flushing - new flushing state.

    • wait_

      public int wait_(ClockTime timeout)

      Wait for activity on the file descriptors in set. This function waits up to the specified timeout. A timeout of GST_CLOCK_TIME_NONE waits forever.

      For GstPoll objects created with gst_poll_new(), this function can only be called from a single thread at a time. If called from multiple threads, -1 will be returned with errno set to EPERM.

      This is not true for timer GstPoll objects created with gst_poll_new_timer(), where it is allowed to have multiple threads waiting simultaneously.

      Parameters:
      timeout - a timeout in nanoseconds.
      Returns:
      The number of GstPollFD in this Poll that have activity or 0 when no activity was detected after timeout. If an error occurs, -1 is returned and errno is set.

    • writeControl

      public boolean writeControl()

      Write a byte to the control socket of the controllable set. This function is mostly useful for timer GstPoll objects created with gst_poll_new_timer().

      It will make any current and future gst_poll_wait() function return with 1, meaning the control socket is set. After an equal amount of calls to gst_poll_read_control() have been performed, calls to gst_poll_wait() will block again until their timeout expired.

      This function only works for timer GstPoll objects created with gst_poll_new_timer().

      Returns:
      true on success. false when when the byte could not be written. errno contains the detailed error code but will never be EAGAIN, EINTR or EWOULDBLOCK. false always signals a critical error.