blob: 302a42338fc443977e2d2c14d818e1fcdae025ae [file] [log] [blame]
// Copyright 2015 The Cobalt Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Module Overview: Starboard Socket Waiter module
//
// 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.
#ifndef STARBOARD_SOCKET_WAITER_H_
#define STARBOARD_SOCKET_WAITER_H_
#include "starboard/export.h"
#include "starboard/socket.h"
#include "starboard/types.h"
#ifdef __cplusplus
extern "C" {
#endif
// Private structure representing a waiter that can wait for many sockets at
// once on a single thread.
typedef struct SbSocketWaiterPrivate SbSocketWaiterPrivate;
// A handle to a socket waiter.
typedef SbSocketWaiterPrivate* SbSocketWaiter;
// All the interests that a socket may register for on a waiter.
typedef enum SbSocketWaiterInterest {
// No interests whatsoever.
kSbSocketWaiterInterestNone = 0,
// An interest in or readiness to read from a socket without blocking.
kSbSocketWaiterInterestRead = 1 << 0,
// An interest in or readiness to write to a socket without blocking.
kSbSocketWaiterInterestWrite = 1 << 1,
} SbSocketWaiterInterest;
// Possible reasons why a call to SbSocketWaiterWaitTimed returned.
typedef enum SbSocketWaiterResult {
// The wait didn't block because the waiter was invalid.
kSbSocketWaiterResultInvalid,
// The wait stopped because the timeout expired.
kSbSocketWaiterResultTimedOut,
// The wait stopped because a call to SbSocketWaiterWakeUp was consumed.
kSbSocketWaiterResultWokenUp,
} SbSocketWaiterResult;
// Function pointer for socket waiter callbacks.
typedef void (*SbSocketWaiterCallback)(SbSocketWaiter waiter,
SbSocket socket,
void* context,
int ready_interests);
// Well-defined value for an invalid socket watcher handle.
#define kSbSocketWaiterInvalid ((SbSocketWaiter)NULL)
// Returns whether the given socket handle is valid.
static inline bool SbSocketWaiterIsValid(SbSocketWaiter watcher) {
return watcher != kSbSocketWaiterInvalid;
}
// Creates and returns a new SbSocketWaiter for the current thread. A socket
// waiter should have a 1:1 relationship to a thread that wants to wait for
// socket activity. There is no reason to create multiple waiters for a single
// thread because the thread can only block on one waiter at a time.
// 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.
SB_EXPORT SbSocketWaiter SbSocketWaiterCreate();
// 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.
//
// |waiter|: The SbSocketWaiter to be destroyed.
SB_EXPORT bool SbSocketWaiterDestroy(SbSocketWaiter waiter);
// 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().
//
// |waiter|: An SbSocketWaiter that waits on the socket for the specified set
// of operations (|interests|).
// |socket|: The SbSocket on which the waiter waits.
// |context|:
// |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.
// |interests|: A bitfield that identifies operations for which the socket is
// waiting.
// |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 before the next call
// to |callback|, even if not all registered |interests| became ready,
// which allows for adding it again in the |callback|.
SB_EXPORT bool SbSocketWaiterAdd(SbSocketWaiter waiter,
SbSocket socket,
void* context,
SbSocketWaiterCallback callback,
int interests,
bool persistent);
// 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|.
//
// |waiter|: The waiter from which the socket is removed.
// |socket|: The socket to remove from the waiter.
SB_EXPORT bool SbSocketWaiterRemove(SbSocketWaiter waiter, SbSocket socket);
// 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.
SB_EXPORT void SbSocketWaiterWait(SbSocketWaiter waiter);
// 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.
//
// |duration|: The minimum amount of time in microseconds 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.
SB_EXPORT SbSocketWaiterResult SbSocketWaiterWaitTimed(SbSocketWaiter waiter,
int64_t duration);
// 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.
//
// |waiter|: The socket waiter to be woken up.
SB_EXPORT void SbSocketWaiterWakeUp(SbSocketWaiter waiter);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // STARBOARD_SOCKET_WAITER_H_