chann

README

This is a vendored version of https://github.com/amyangfei/chann/tree/should-consume-data-after-close - that exists here due to an unfixed bug in https://github.com/golang-design/chann/pull/5

gparallel uses a vendored version of chann instaad of a replace directive in the go.mod file, to be able to be installed with a simple go install - which doesn't work if there are any replace directives present.

Documentation

Overview

Package chann providesa a unified channel package.

The package is compatible with existing buffered and unbuffered channels. For example, in Go, to create a buffered or unbuffered channel, one uses built-in function `make` to create a channel:

ch := make(chan int)     // unbuffered channel
ch := make(chan int, 42) // or buffered channel

However, all these channels have a finite capacity for caching, and it is impossible to create a channel with unlimited capacity, namely, an unbounded channel.

This package provides the ability to create all possible types of channels. To create an unbuffered or a buffered channel:

ch := chann.New[int](chann.Cap(0))  // unbuffered channel
ch := chann.New[int](chann.Cap(42)) // or buffered channel

More importantly, when the capacity of the channel is unspecified, or provided as negative values, the created channel is an unbounded channel:

ch := chann.New[int]()               // unbounded channel
ch := chann.New[int](chann.Cap(-42)) // or unbounded channel

Furthermore, all channels provides methods to send (In()), receive (Out()), and close (Close()).

Note that to close a channel, must use Close() method instead of the language built-in method Two additional methods: ApproxLen and Cap returns the current status of the channel: an approximation of the current length of the channel, as well as the current capacity of the channel.

See https://golang.design/research/ultimate-channel to understand the motivation of providing this package and the possible use cases with this package.

Index

• type Chann
  • func New[T any](opts ...Opt) *Chann[T]
  • func (ch *Chann[T]) Cap() int
  • func (ch *Chann[T]) Close()
  • func (ch *Chann[T]) In() chan<- T
  • func (ch *Chann[T]) Len() int
  • func (ch *Chann[T]) Out() <-chan T
• type Opt
  • func Cap(n int) Opt

Types

type Chann

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

Chann is a generic channel abstraction that can be either buffered, unbuffered, or unbounded. To create a new channel, use New to allocate one, and use Cap to configure the capacity of the channel.

func New

func New[T any](opts ...Opt) *Chann[T]

New returns a Chann that may be a buffered, an unbuffered or an unbounded channel. To configure the type of the channel, use Cap.

By default, or without specification, the function returns an unbounded channel with unlimited capacity.

	ch := chann.New[float64]()
	// or
 ch := chann.New[float64](chann.Cap(-1))

If the chann.Cap specified a non-negative integer, the returned channel is either unbuffered (0) or buffered (positive).

An unbounded channel is not a buffered channel with infinite capacity, and they have different memory model semantics in terms of receiving a value: The recipient of a buffered channel is immediately available after a send is complete. However, the recipient of an unbounded channel may be available within a bounded time frame after a send is complete.

Note that although the input arguments are specified as variadic parameter list, however, the function panics if there is more than one option is provided.

func (*Chann[T]) Cap

func (ch *Chann[T]) Cap() int

Cap returns the capacity of the channel.

func (*Chann[T]) Close

func (ch *Chann[T]) Close()

Close closes the channel gracefully.

func (*Chann[T]) In

func (ch *Chann[T]) In() chan<- T

In returns the send channel of the given Chann, which can be used to send values to the channel. If one closes the channel using close(), it will result in a runtime panic. Instead, use Close() method.

func (*Chann[T]) Len

func (ch *Chann[T]) Len() int

Len returns an approximation of the length of the channel.

Note that in a concurrent scenario, the returned length of a channel may never be accurate. Hence the function is named with an Approx prefix.

func (*Chann[T]) Out

func (ch *Chann[T]) Out() <-chan T

Out returns the receive channel of the given Chann, which can be used to receive values from the channel.

type Opt

type Opt func(*config)

Opt represents an option to configure the created channel. The current possible option is Cap.

func Cap

func Cap(n int) Opt

Cap is the option to configure the capacity of a creating buffer. if the provided number is 0, Cap configures the creating buffer to a unbuffered channel; if the provided number is a positive integer, then Cap configures the creating buffer to a buffered channel with the given number of capacity for caching. If n is a negative integer, then it configures the creating channel to become an unbounded channel.