gate

Documentation

Overview

Package gate provides a usage Gate synchronization primitive.

Index

• type Gate
  • func (g *Gate) Close()
  • func (g *Gate) Enter() bool
  • func (g *Gate) Leave()

Types

type Gate

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

Gate is a synchronization primitive that allows concurrent goroutines to "enter" it as long as it hasn't been closed yet. Once it's been closed, goroutines cannot enter it anymore, but are allowed to leave, and the closer will be informed when all goroutines have left.

Many goroutines are allowed to enter the gate concurrently, but only one is allowed to close it.

This is similar to a r/w critical section, except that goroutines "entering" never block: they either enter immediately or fail to enter. The closer will block waiting for all goroutines currently inside the gate to leave.

This function is implemented efficiently. On x86, only one interlocked operation is performed on enter, and one on leave.

This is useful, for example, in cases when a goroutine is trying to clean up an object for which multiple goroutines have pointers. In such a case, users would be required to enter and leave the gates, and the cleaner would wait until all users are gone (and no new ones are allowed) before proceeding.

Users:

if !g.Enter() {
	// Gate is closed, we can't use the object.
	return
}

// Do something with object.
[...]

g.Leave()

Closer:

// Prevent new users from using the object, and wait for the existing
// ones to complete.
g.Close()

// Clean up the object.
[...]

func (*Gate) Close

func (g *Gate) Close()

Close closes the gate for entering, and waits until all goroutines [that are currently inside the gate] leave before returning.

Only one goroutine can call this function.

func (*Gate) Enter

func (g *Gate) Enter() bool

Enter tries to enter the gate. It will succeed if it hasn't been closed yet, in which case the caller must eventually call Leave().

This function is thread-safe.

func (*Gate) Leave

func (g *Gate) Leave()

Leave leaves the gate. This must only be called after a successful call to Enter(). If the gate has been closed and this is the last one inside the gate, it will notify the closer that the gate is done.

This function is thread-safe.