chops

Documentation

Overview

Package chops provides useful channel operations that are not provided by the standard `<-` mechanism. It is not guaranteed to be compatible with all versions of Go, although it is tested on Go 1.18.

Index

• func IsClosed[T any](ch chan T) bool
• func TryClose[T any](ch chan<- T) (ok bool)
• func Wait(wg *sync.WaitGroup) <-chan struct{}
• type Result
  • func TryRecv[T any](ch <-chan T) Result[T]
  • func (r Result[T]) Get() (T, Status)
  • func (r Result[T]) Match(ok func(T), closed, blocked func())
• type Status
  • func TrySend[T any](ch chan<- T, x T) (stat Status)
  • func (s Status) String() string

Functions

func IsClosed

func IsClosed[T any](ch chan T) bool

IsClosed returns true if the channel provided is closed. You cannot assume that the channel is not closed if this function returns false. The channel may still contain data to be read, use `len()` to determine that.

func TryClose

func TryClose[T any](ch chan<- T) (ok bool)

TryClose ensures a channel is closed. It returns true if the channel was previously open, or false if the channel was already closed at the time of the call.

You should not need to use this function normally, since only the sender should close a channel.

func Wait

func Wait(wg *sync.WaitGroup) <-chan struct{}

Wait returns a channel that is closed once wg's counter is 0. This allows WaitGroups to participate in selects, like so:

var wg sync.WaitGroup
wg.Add(n)

select {
case <-ctx.Done(): // for example
	...
case <-chops.Wait(&wg):
	...
}

This is a one-shot event. If wg is reused after its counter is decremented to 0, the channel does not reset or reopen (this is impossible under channel semantics, anyway).

Wait creates a goroutine that exits when the WaitGroup is Done.

Types

type Result

type Result[T any] struct {
	// contains filtered or unexported fields
}

func TryRecv

func TryRecv[T any](ch <-chan T) Result[T]

TryRecv attempts a non-blocking receive from a channel.

func (Result[T]) Get

func (r Result[T]) Get() (T, Status)

Get returns the result of the channel operation: If the return Status is Ok, the receive succeeded and the returned T is the channel element. If the return Status is Closed, the channel is closed and the returned T will be the zero value of T. If the return Status is Blocked, the channel is empty (but not closed, at the time of the receive) and the returned T will be the zero value of T.

func (Result[T]) Match

func (r Result[T]) Match(ok func(T), closed, blocked func())

Match performs an exhaustive match on the Result.

type Status

type Status int

Status represents the result of a non-blocking channel operation. It can be Ok, Closed, or Blocked.

const (
	// The channel accepted the send or receive without
	// blocking.
	Ok Status = iota
	// The channel is closed. Future operations will always
	// return Closed again.
	Closed
	// The channel is not ready to accept the operation.
	// Its buffer could be full, or if it's unbuffered, no
	// goroutine is waiting on the other end.
	Blocked
)

func TrySend

func TrySend[T any](ch chan<- T, x T) (stat Status)

TrySend attempts a non-blocking send to a channel. If the return Status is Ok, the send succeeded. If the return Status is Closed, the channel is closed. Future calls to TrySend will continue to return Closed. If the return Status is Blocked, the channel is either full (if it is buffered) or nobody is listening on the other end (if it is unbuffered).

func (Status) String

func (s Status) String() string