Starboard Module Reference: socket_waiter.h

Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to:

  1. Create its own SbSocketWaiter.
  2. Wait on the SbSocketWaiter, indefinitely if no scheduled tasks, or timed if there are scheduled future tasks.
  3. While waiting, the SbSocketWaiter will call back to service ready SbSockets.
  4. Wake up, if signaled to do so.
  5. If ready to exit, go to 7.
  6. Add and remove SbSockets to and from the SbSocketWaiter, and go to 2.
  7. Destroy its SbSocketWaiter and exit.
If another thread wants to queue immediate or schedule future work on the I/O thread, it needs to call SbSocketWaiterWakeUp() on the SbSocketWaiter after queuing the work item, or the SbSocketWaiter is not otherwise guaranteed to wake up.

Enums

SbSocketWaiterInterest

All the interests that a socket may register for on a waiter.

Values

  • kSbSocketWaiterInterestNone - No interests whatsoever.
  • kSbSocketWaiterInterestRead - An interest in or readiness to read from a socket without blocking.
  • kSbSocketWaiterInterestWrite - An interest in or readiness to write to a socket without blocking.

SbSocketWaiterResult

Possible reasons why a call to SbSocketWaiterWaitTimed returned.

Values

  • kSbSocketWaiterResultInvalid - The wait didn't block because the waiter was invalid.
  • kSbSocketWaiterResultTimedOut - The wait stopped because the timeout expired.
  • kSbSocketWaiterResultWokenUp - The wait stopped because a call to SbSocketWaiterWakeUp was consumed.

Structs

SbSocketWaiterPrivate

Private structure representing a waiter that can wait for many sockets at once on a single thread.

Functions

SbSocketWaiterAdd

Description

Adds a new socket to be waited on by the waiter with a bitfield of interests. This function should only be called on the thread that waits on this waiter.
If socket is already registered with this or another waiter, the function does nothing and returns false. The client must remove the socket and then add it back with the new interests.
If socket is already ready for one or more of the operations set in the interests mask, then the callback will be called on the next call to either SbSocketWaiterWait() or SbSocketWaiterWaitTimed().

Declaration and definitions

SB_EXPORT bool SbSocketWaiterAdd(SbSocketWaiter waiter,
                                 SbSocket socket,
                                 void* context,
                                 SbSocketWaiterCallback callback,
                                 int interests,
                                 bool persistent);

#include "starboard/socket_waiter.h"

bool SbSocketWaiterAdd(SbSocketWaiter /*waiter*/,
                       SbSocket /*socket*/,
                       void* /*context*/,
                       SbSocketWaiterCallback /*callback*/,
                       int /*interests*/,
                       bool /*persistent*/) {
  return false;
}

Parameters

Parameters
SbSocketWaiter
waiter
An SbSocketWaiter that waits on the socket for the specified set of operations (interests).
SbSocket
socket
The SbSocket on which the waiter waits.
void*
context
SbSocketWaiterCallback
callback
The function that is called when the event fires. The waiter, socket, context are all passed to the callback, along with a bitfield of interests that the socket is actually ready for.
int
interests
A bitfield that identifies operations for which the socket is waiting.
bool
persistent
Identifies the procedure that will be followed for removing the socket:
  • If persistent is true, then socket stays registered with waiter until SbSocketWaiterRemove() is called with waiter and socket.
  • If persistent is false, then socket is removed after the next call to callback, even if not all registered interests became ready.

SbSocketWaiterCreate

Description

The results of two threads waiting on the same waiter is undefined and will not work. Except for the SbSocketWaiterWakeUp() function, SbSocketWaiters are not thread-safe and don't expect to be modified concurrently.

Declaration and definitions

SB_EXPORT SbSocketWaiter SbSocketWaiterCreate();

#include "starboard/socket_waiter.h"

SbSocketWaiter SbSocketWaiterCreate() {
  return kSbSocketWaiterInvalid;
}

SbSocketWaiterDestroy

Description

Destroys waiter and removes all sockets still registered by way of SbSocketWaiterAdd. This function may be called on any thread as long as there is no risk of concurrent access to the waiter.

Declaration and definitions

SB_EXPORT bool SbSocketWaiterDestroy(SbSocketWaiter waiter);

#include "starboard/socket_waiter.h"

bool SbSocketWaiterDestroy(SbSocketWaiter /*waiter*/) {
  return false;
}

Parameters

Parameters
SbSocketWaiter
waiter
The SbSocketWaiter to be destroyed.

SbSocketWaiterIsValid

Description

Returns whether the given socket handle is valid.

Declaration

static SB_C_INLINE bool SbSocketWaiterIsValid(SbSocketWaiter watcher) {
  return watcher != kSbSocketWaiterInvalid;
}

Parameters

Parameters
SbSocketWaiter
watcher

SbSocketWaiterRemove

Description

Removes a socket, previously added with SbSocketWaiterAdd(), from a waiter. This function should only be called on the thread that waits on this waiter.
The return value indicates whether the waiter still waits on the socket. If socket wasn't registered with waiter, then the function is a no-op and returns true.

Declaration and definitions

SB_EXPORT bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket);

#include "starboard/socket_waiter.h"

bool SbSocketWaiterRemove(SbSocketWaiter /*waiter*/, SbSocket /*socket*/) {
  return false;
}

Parameters

Parameters
SbSocketWaiter
waiter
The waiter from which the socket is removed.
SbSocket
socket
The socket to remove from the waiter.

SbSocketWaiterWait

Description

Waits on all registered sockets, calling the registered callbacks if and when the corresponding sockets become ready for an interested operation. This version exits only after SbSocketWaiterWakeUp() is called. This function should only be called on the thread that waits on this waiter.

Declaration and definitions

SB_EXPORT void SbSocketWaiterWait(SbSocketWaiter waiter);

#include "starboard/socket_waiter.h"

void SbSocketWaiterWait(SbSocketWaiter /*waiter*/) {
}

Parameters

Parameters
SbSocketWaiter
waiter

SbSocketWaiterWaitTimed

Description

Behaves similarly to SbSocketWaiterWait(), but this function also causes waiter to exit on its own after at least duration has passed if SbSocketWaiterWakeUp() it not called by that time.
The return value indicates the reason that the socket waiter exited. This function should only be called on the thread that waits on this waiter.

Declaration and definitions

SB_EXPORT SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter,
                                                       SbTime duration);

#include "starboard/socket_waiter.h"

SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter /*waiter*/,
                                             SbTime /*duration*/) {
  return kSbSocketWaiterResultInvalid;
}

Parameters

Parameters
SbSocketWaiter
waiter
SbTime
duration
The minimum amount of time after which the socket waiter should exit if it is not woken up before then. As with SbThreadSleep() (see thread.h), this function may wait longer than duration, such as if the timeout expires while a callback is being fired.

SbSocketWaiterWakeUp

Description

Wakes up waiter once. This is the only thread-safe waiter function. It can can be called from a SbSocketWaiterCallback to wake up its own waiter, and it can also be called from another thread at any time. In either case, the waiter will exit the next wait gracefully, first completing any in-progress callback.
Each time this function is called, it causes the waiter to wake up once, regardless of whether the waiter is currently waiting. If the waiter is not waiting, the function takes effect immediately the next time the waiter waits. The number of wake-ups accumulates, and the queue is only consumed as the waiter waits and then is subsequently woken up again. For example, if you call this function 7 times, then SbSocketWaiterWait() and WaitTimed() will not block the next 7 times they are called.

Declaration and definitions

SB_EXPORT void SbSocketWaiterWakeUp(SbSocketWaiter waiter);

#include "starboard/socket_waiter.h"

void SbSocketWaiterWakeUp(SbSocketWaiter /*waiter*/) {
}

Parameters

Parameters
SbSocketWaiter
waiter
The socket waiter to be woken up.