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()).
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 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
New returns a Chann that may represent a buffered, an unbuffered or an unbounded channel. To configure the type of the channel, one may pass Cap as the argument of this function.
By default, or without specification, the function returns an unbounded channel which has 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).
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. DEPRECATED: use NewAutoDrainChann instead.
func (*Chann[T]) Close ¶
func (ch *Chann[T]) Close()
Close closes the channel gracefully. DEPRECATED: use CloseAndDrain instead.
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.
type DrainableChann ¶
type DrainableChann[T any] struct { // contains filtered or unexported fields }
DrainableChann is a channel that will be drained when it is closed. It is a wrapper of Chann. NOTICE: Please make sure that it is safe to drain rest elements in the channel before closing the channel.
func NewAutoDrainChann ¶
func NewAutoDrainChann[T any](opts ...Opt) *DrainableChann[T]
NewAutoDrainChann creates a new DrainableChann.
func (*DrainableChann[T]) Cap ¶
func (ch *DrainableChann[T]) Cap() int
Cap returns the capacity of the channel.
func (*DrainableChann[T]) CloseAndDrain ¶
func (ch *DrainableChann[T]) CloseAndDrain()
CloseAndDrain closes the channel and drains the channel to avoid the goroutine leak.
func (*DrainableChann[T]) In ¶
func (ch *DrainableChann[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 CloseAndDrain() method.
func (*DrainableChann[T]) Len ¶
func (ch *DrainableChann[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 (*DrainableChann[T]) Out ¶
func (ch *DrainableChann[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 ¶
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.
Source Files