waiter

package
v0.0.0-...-4bf4b70 Latest Latest
Warning

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

Go to latest
Published: Jan 24, 2021 License: Apache-2.0, MIT 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 {
	Callback EntryCallback
	// 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.

+stateify savable

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.

func (*Entry) Next

func (e *Entry) Next() *Entry

Next returns the entry that follows e in the list.

func (*Entry) Prev

func (e *Entry) Prev() *Entry

Prev returns the entry that precedes e in the list.

func (*Entry) SetNext

func (e *Entry) SetNext(elem *Entry)

SetNext assigns 'entry' as the entry that follows e in the list.

func (*Entry) SetPrev

func (e *Entry) SetPrev(elem *Entry)

SetPrev assigns 'entry' as the entry that precedes e in the list.

func (*Entry) StateFields

func (e *Entry) StateFields() []string

func (*Entry) StateLoad

func (e *Entry) StateLoad(stateSourceObject state.Source)

func (*Entry) StateSave

func (e *Entry) StateSave(stateSinkObject state.Sink)

func (*Entry) StateTypeName

func (e *Entry) StateTypeName() string

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.
	//
	// The mask indicates the events that occurred and that the entry is
	// interested in.
	Callback(e *Entry, mask EventMask)
}

EntryCallback provides a notify callback.

type EventMask

type EventMask uint64

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

const (
	EventIn  EventMask = 0x01 // POLLIN
	EventPri EventMask = 0x02 // POLLPRI
	EventOut EventMask = 0x04 // POLLOUT
	EventErr EventMask = 0x08 // POLLERR
	EventHUp EventMask = 0x10 // POLLHUP

)

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

func EventMaskFromLinux

func EventMaskFromLinux(e uint32) EventMask

EventMaskFromLinux returns an EventMask representing the supported events from the Linux events e, which is in the format used by poll(2).

func (EventMask) ToLinux

func (e EventMask) ToLinux() uint32

ToLinux returns e in the format used by Linux poll(2).

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.

+stateify savable

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.

func (*Queue) StateFields

func (q *Queue) StateFields() []string

func (*Queue) StateLoad

func (q *Queue) StateLoad(stateSourceObject state.Source)

func (*Queue) StateSave

func (q *Queue) StateSave(stateSinkObject state.Sink)

func (*Queue) StateTypeName

func (q *Queue) StateTypeName() string

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.

Jump to

Keyboard shortcuts

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