README
¶
chann 
a unified channel package in Go
import "golang.design/x/chann"
This package requires Go 1.18.
Basic Usage
Different types of channels:
ch := chann.New[int]() // unbounded, capacity unlimited
ch := chann.New[func()](chann.Cap(0)) // unbufferd, capacity 0
ch := chann.New[string](chann.Cap(100)) // buffered, capacity 100
Send and receive operations:
ch.In() <- 42
println(<-ch.Out()) // 42
Close operation:
ch.Close()
Channel properties:
ch.Len() // the length of the channel
ch.Cap() // the capacity of the channel
See https://golang.design/research/ultimate-channel for more details of the motivation of this abstraction.
License
MIT | © 2021 The golang.design Initiative Authors, written by Changkun Ou.
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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Ranger ¶
Ranger returns a Sender and a Receiver. The Receiver provides a Next method to retrieve values. The Sender provides a Send method to send values and a Close method to stop sending values. The Next method indicates when the Sender has been closed, and the Send method indicates when the Receiver has been freed.
This is a convenient way to exit a goroutine sending values when the receiver stops reading them.
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.
Example ¶
package main
import (
"fmt"
"golang.design/x/chann"
)
func main() {
ch := chann.New[int]()
go func() {
for i := 0; i < 10; i++ {
ch.In() <- i // never block
}
ch.Close()
}()
sum := 0
for i := range ch.Out() {
sum += i
}
fmt.Println(sum)
}
Output: 45
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 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.
type Receiver ¶
type Receiver[T any] struct { // contains filtered or unexported fields }
A Receiver receives values from a Sender.
type Sender ¶
type Sender[T any] struct { // contains filtered or unexported fields }
A sender is used to send values to a Receiver.
Source Files