Allows a thread to wait on many sockets at once. The standard usage pattern would be for a single I/O thread to:
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.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.Private structure representing a waiter that can wait for many sockets at once on a single thread.
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
#include "starboard/socket_waiter.h"
bool SbSocketWaiterAdd(SbSocketWaiter /*waiter*/,
SbSocket /*socket*/,
void* /*context*/,
SbSocketWaiterCallback /*callback*/,
int /*interests*/,
bool /*persistent*/) {
return false;
}
Parameters
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
#include "starboard/socket_waiter.h"
SbSocketWaiter SbSocketWaiterCreate() {
return kSbSocketWaiterInvalid;
}
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
#include "starboard/socket_waiter.h"
bool SbSocketWaiterDestroy(SbSocketWaiter /*waiter*/) {
return false;
}
Parameters
Description
Returns whether the given socket handle is valid.
Declaration
static SB_C_INLINE bool SbSocketWaiterIsValid(SbSocketWaiter watcher) {
return watcher != kSbSocketWaiterInvalid;
}
Parameters
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
#include "starboard/socket_waiter.h"
bool SbSocketWaiterRemove(SbSocketWaiter /*waiter*/, SbSocket /*socket*/) {
return false;
}
Parameters
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
#include "starboard/socket_waiter.h"
void SbSocketWaiterWait(SbSocketWaiter /*waiter*/) {
}
Parameters
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
#include "starboard/socket_waiter.h"
SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter /*waiter*/,
SbTime /*duration*/) {
return kSbSocketWaiterResultInvalid;
}
Parameters
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
#include "starboard/socket_waiter.h"
void SbSocketWaiterWakeUp(SbSocketWaiter /*waiter*/) {
}
Parameters