sync

Documentation

Index

• Variables
• type Limiter
  • func NewLimiter(limit int) *Limiter
  • func (l *Limiter) Release(n int)
  • func (l *Limiter) Request(n int, cancel <-chan struct{}) bool
  • func (l *Limiter) SetLimit(limit int)
• type RWMutex
  • func New(maxLockTime time.Duration, callDepth int) *RWMutex
  • func (rwm *RWMutex) Lock() int
  • func (rwm *RWMutex) RLock() int
  • func (rwm *RWMutex) RUnlock(id int)
  • func (rwm *RWMutex) Unlock(id int)
• type ThreadGroup
  • func (tg *ThreadGroup) Add() error
  • func (tg *ThreadGroup) AfterStop(fn func())
  • func (tg *ThreadGroup) Done()
  • func (tg *ThreadGroup) Flush() error
  • func (tg *ThreadGroup) OnStop(fn func())
  • func (tg *ThreadGroup) Stop() error
  • func (tg *ThreadGroup) StopChan() <-chan struct{}
  • func (tg *ThreadGroup) StopCtx() context.Context
• type TryMutex
  • func (tm *TryMutex) Lock()
  • func (tm *TryMutex) TryLock() bool
  • func (tm *TryMutex) TryLockTimed(t time.Duration) bool
  • func (tm *TryMutex) Unlock()
• type TryRWMutex
  • func (tm *TryRWMutex) Lock()
  • func (tm *TryRWMutex) RLock()
  • func (tm *TryRWMutex) RUnlock()
  • func (tm *TryRWMutex) TryLock() bool
  • func (tm *TryRWMutex) TryRLock() bool
  • func (tm *TryRWMutex) Unlock()

Variables

var ErrStopped = errors.New("ThreadGroup already stopped")

ErrStopped is returned by ThreadGroup methods if Stop has already been called.

Types

type Limiter

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

A Limiter restricts access to a resource.

Units of the resource are reserved via Request and returned via Release. Conventionally, a caller who reserves n units is responsible for ensuring that all n are eventually returned. Once the number of reserved units exceeds the Limiters limit, further calls to Request will block until sufficient units are returned via Release.

This Limiter differs from others in that it allows requesting more than the limit. This request is only fulfilled once all other units have been returned. Once the request is fulfilled, calls to Request will block until enough units have been returned to bring the total outlay below the limit. This design choice prevents any call to Request from blocking forever, striking a balance between precise resource management and flexibility.

func NewLimiter

func NewLimiter(limit int) *Limiter

NewLimiter returns a Limiter with the supplied limit.

func (*Limiter) Release

func (l *Limiter) Release(n int)

Release returns n units to l, making them available to future callers. It is legal for n to be larger than l's limit, as long as n was previously passed to Request.

func (*Limiter) Request

func (l *Limiter) Request(n int, cancel <-chan struct{}) bool

Request blocks until n units are available. If n is greater than m's limit, Request blocks until all of m's units have been released.

Request is unbiased with respect to n: calls with small n do not starve calls with large n.

Request returns true if the request was canceled, and false otherwise.

func (*Limiter) SetLimit

func (l *Limiter) SetLimit(limit int)

SetLimit sets the limit of l. It is legal to interpose calls to SetLimit between Request/Release pairs.

type RWMutex

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

RWMutex provides locking functions, and an ability to detect and remove deadlocks.

func New

func New(maxLockTime time.Duration, callDepth int) *RWMutex

New takes a maxLockTime and returns a lock. The lock will never stay locked for more than maxLockTime, instead printing an error and unlocking after maxLockTime has passed.

func (*RWMutex) Lock

func (rwm *RWMutex) Lock() int

Lock will lock the RWMutex. The return value must be used as input when calling RUnlock.

func (*RWMutex) RLock

func (rwm *RWMutex) RLock() int

RLock will read lock the RWMutex. The return value must be used as input when calling RUnlock.

func (*RWMutex) RUnlock

func (rwm *RWMutex) RUnlock(id int)

RUnlock will read unlock the RWMutex. The return value of calling RLock must be used as input.

func (*RWMutex) Unlock

func (rwm *RWMutex) Unlock(id int)

Unlock will unlock the RWMutex. The return value of calling Lock must be used as input.

type ThreadGroup

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

A ThreadGroup is a one-time-use object to manage the life cycle of a group of threads. It is a sync.WaitGroup that provides functions for coordinating actions and shutting down threads. After Stop() is called, the thread group is no longer useful.

It is safe to call Add(), Done(), and Stop() concurrently, however it is not safe to nest calls to Add(). A simple example of a nested call to add would be:

tg.Add()
tg.Add()
tg.Done()
tg.Done()

func (*ThreadGroup) Add

func (tg *ThreadGroup) Add() error

Add increments the thread group counter.

func (*ThreadGroup) AfterStop

func (tg *ThreadGroup) AfterStop(fn func())

AfterStop ensures that a function will be called after Stop() has been called and after all running routines have called Done(). The functions will be called in reverse order to how they were added, similar to defer. If Stop() has already been called, the input function will be called immediately.

The primary use of AfterStop is to allow code that opens and closes resources to be positioned next to each other. The purpose is similar to `defer`, except for resources that outlive the function which creates them.

func (*ThreadGroup) Done

func (tg *ThreadGroup) Done()

Done decrements the thread group counter.

func (*ThreadGroup) Flush

func (tg *ThreadGroup) Flush() error

Flush will block all calls to 'tg.Add' until all current routines have called 'tg.Done'. This in effect 'flushes' the module, letting it complete any tasks that are open before taking on new ones.

func (*ThreadGroup) OnStop

func (tg *ThreadGroup) OnStop(fn func())

OnStop ensures that a function will be called after Stop() has been called, and before blocking until all running routines have called Done(). It is safe to use OnStop to coordinate the closing of long-running threads. The OnStop functions will be called in the reverse order in which they were added, similar to defer. If Stop() has already been called, the input function will be called immediately.

func (*ThreadGroup) Stop

func (tg *ThreadGroup) Stop() error

Stop will close the stop channel of the thread group, then call all 'OnStop' functions in reverse order, then will wait until the thread group counter reaches zero, then will call all of the 'AfterStop' functions in reverse order. After Stop is called, most actions will return ErrStopped.

func (*ThreadGroup) StopChan

func (tg *ThreadGroup) StopChan() <-chan struct{}

StopChan provides read-only access to the ThreadGroup's stopChan. Callers should select on StopChan in order to interrupt long-running reads (such as time.After).

func (*ThreadGroup) StopCtx

func (tg *ThreadGroup) StopCtx() context.Context

StopCtx returns the threadgroups underlying context.

type TryMutex

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

TryMutex provides a mutex that allows you to attempt to grab a mutex, and then fail if the mutex is either not grabbed immediately or is not grabbed by the specified duration.

func (*TryMutex) Lock

func (tm *TryMutex) Lock()

Lock grabs a lock on the TryMutex, blocking until the lock is obtained.

func (*TryMutex) TryLock

func (tm *TryMutex) TryLock() bool

TryLock grabs a lock on the TryMutex, returning an error if the mutex is already locked.

func (*TryMutex) TryLockTimed

func (tm *TryMutex) TryLockTimed(t time.Duration) bool

TryLockTimed grabs a lock on the TryMutex, returning an error if the mutex is not grabbed after the provided duration.

func (*TryMutex) Unlock

func (tm *TryMutex) Unlock()

Unlock releases a lock on the TryMutex.

type TryRWMutex

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

TryRWMutex allows you to try to grab a RWMutex, failing if the mutex is unavailable. Standard blocking RLock and Lock calls also available.

Note that there will be inconsistencies if there are more than 1 << 20 operations active at once.

func (*TryRWMutex) Lock

func (tm *TryRWMutex) Lock()

Lock blocks until the mutex is available, and then locks it.

func (*TryRWMutex) RLock

func (tm *TryRWMutex) RLock()

RLock blocks until the mutex is available, then grabs a read lock.

func (*TryRWMutex) RUnlock

func (tm *TryRWMutex) RUnlock()

RUnlock releases a read lock on the mutex.

func (*TryRWMutex) TryLock

func (tm *TryRWMutex) TryLock() bool

TryLock grabs a lock on the mutex, returning false if the mutex is unavailable.

func (*TryRWMutex) TryRLock

func (tm *TryRWMutex) TryRLock() bool

TryRLock grabs a read lock on the mutex, returning false if the mutex is already locked.

func (*TryRWMutex) Unlock

func (tm *TryRWMutex) Unlock()

Unlock releases a lock on the mutex.