starboard/socket_waiter.h - cobalt - Git at Google

 // 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_
	// 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_