waiter

package
v0.0.0-...-23e6066 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 3, 2018 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package waiter provides the implementation of a wait queue, where waiters can be enqueued to be notified when an event of interest happens.

Becoming readable and/or writable are examples of events. Waiters are expected to use a pattern similar to this to make a blocking function out of a non-blocking one:

func (o *object) blockingRead(...) error {
	err := o.nonBlockingRead(...)
	if err != ErrAgain {
		// Completed with no need to wait!
		return err
	}

	e := createOrGetWaiterEntry(...)
	o.EventRegister(&e, waiter.EventIn)
	defer o.EventUnregister(&e)

	// We need to try to read again after registration because the
	// object may have become readable between the last attempt to
	// read and read registration.
	err = o.nonBlockingRead(...)
	for err == ErrAgain {
		wait()
		err = o.nonBlockingRead(...)
	}

	return err
}

Another goroutine needs to notify waiters when events happen. For example:

func (o *object) Write(...) ... {
	// Do write work.
	[...]

	if oldDataAvailableSize == 0 && dataAvailableSize > 0 {
		// If no data was available and now some data is
		// available, the object became readable, so notify
		// potential waiters about this.
		o.Notify(waiter.EventIn)
	}
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AlwaysReady

type AlwaysReady struct {
}

AlwaysReady implements the Waitable interface but is always ready. Embedding this struct into another struct makes it implement the boilerplate empty functions automatically.

func (*AlwaysReady) EventRegister

func (*AlwaysReady) EventRegister(*Entry, EventMask)

EventRegister doesn't do anything because this object doesn't need to issue notifications because its readiness never changes.

func (*AlwaysReady) EventUnregister

func (*AlwaysReady) EventUnregister(e *Entry)

EventUnregister doesn't do anything because this object doesn't need to issue notifications because its readiness never changes.

func (*AlwaysReady) Readiness

func (*AlwaysReady) Readiness(mask EventMask) EventMask

Readiness always returns the input mask because this object is always ready.

type Entry

type Entry struct {
	// Context stores any state the waiter may wish to store in the entry
	// itself, which may be used at wake up time.
	//
	// Note that use of this field is optional and state may alternatively be
	// stored in the callback itself.
	Context interface{}

	Callback EntryCallback

	ilist.Entry
	// contains filtered or unexported fields
}

Entry represents a waiter that can be add to the a wait queue. It can only be in one queue at a time, and is added "intrusively" to the queue with no extra memory allocations.

func NewChannelEntry

func NewChannelEntry(c chan struct{}) (Entry, chan struct{})

NewChannelEntry initializes a new Entry that does a non-blocking write to a struct{} channel when the callback is called. It returns the new Entry instance and the channel being used.

If a channel isn't specified (i.e., if "c" is nil), then NewChannelEntry allocates a new channel.

type EntryCallback

type EntryCallback interface {
	// Callback is the function to be called when the waiter entry is
	// notified. It is responsible for doing whatever is needed to wake up
	// the waiter.
	//
	// The callback is supposed to perform minimal work, and cannot call
	// any method on the queue itself because it will be locked while the
	// callback is running.
	Callback(e *Entry)
}

EntryCallback provides a notify callback.

type EventMask

type EventMask uint16

EventMask represents io events as used in the poll() syscall.

const (
	EventIn   EventMask = 0x01 // syscall.EPOLLIN
	EventPri  EventMask = 0x02 // syscall.EPOLLPRI
	EventOut  EventMask = 0x04 // syscall.EPOLLOUT
	EventErr  EventMask = 0x08 // syscall.EPOLLERR
	EventHUp  EventMask = 0x10 // syscall.EPOLLHUP
	EventNVal EventMask = 0x20 // Not defined in syscall.
)

Events that waiters can wait on. The meaning is the same as those in the poll() syscall.

type Queue

type Queue struct {
	// contains filtered or unexported fields
}

Queue represents the wait queue where waiters can be added and notifiers can notify them when events happen.

The zero value for waiter.Queue is an empty queue ready for use.

func (*Queue) EventRegister

func (q *Queue) EventRegister(e *Entry, mask EventMask)

EventRegister adds a waiter to the wait queue; the waiter will be notified when at least one of the events specified in mask happens.

func (*Queue) EventUnregister

func (q *Queue) EventUnregister(e *Entry)

EventUnregister removes the given waiter entry from the wait queue.

func (*Queue) Events

func (q *Queue) Events() EventMask

Events returns the set of events being waited on. It is the union of the masks of all registered entries.

func (*Queue) IsEmpty

func (q *Queue) IsEmpty() bool

IsEmpty returns if the wait queue is empty or not.

func (*Queue) Notify

func (q *Queue) Notify(mask EventMask)

Notify notifies all waiters in the queue whose masks have at least one bit in common with the notification mask.

type Waitable

type Waitable interface {
	// Readiness returns what the object is currently ready for. If it's
	// not ready for a desired purpose, the caller may use EventRegister and
	// EventUnregister to get notifications once the object becomes ready.
	//
	// Implementations should allow for events like EventHUp and EventErr
	// to be returned regardless of whether they are in the input EventMask.
	Readiness(mask EventMask) EventMask

	// EventRegister registers the given waiter entry to receive
	// notifications when an event occurs that makes the object ready for
	// at least one of the events in mask.
	EventRegister(e *Entry, mask EventMask)

	// EventUnregister unregisters a waiter entry previously registered with
	// EventRegister().
	EventUnregister(e *Entry)
}

Waitable contains the methods that need to be implemented by waitable objects.

Directories

Path Synopsis
Package fdnotifier contains an adapter that translates IO events (e.g., a file became readable/writable) from native FDs to the notifications in the waiter package.
Package fdnotifier contains an adapter that translates IO events (e.g., a file became readable/writable) from native FDs to the notifications in the waiter package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL