go_channels 0.2.1

go_channels: ^0.2.1 copied to clipboard

• Add benchmark/capacity_benchmark.dart and document what buffer capacity actually buys. Moving 200,000 values from one task to another, every buffered size (1, 16, 256, 4096) lands within a few percent of every other and about 10% above the unbuffered rendezvous, and draining through select measured slightly faster than a direct receive. Capacity is a backpressure decision, not a throughput one, and the README now says so with the chart.

  Two things the benchmark had to get right to be worth reading: the plain case drains with receiveOr rather than ch.stream, because the stream wraps every value in a StreamController event and would have measured Dart's stream machinery instead of the channel; and every case asserts it moved all 200,000 values, so the rows are comparable. The claim that a waiting rendezvous does not block the isolate is measured too — a 1 ms timer fires 20 times in 20 ms with a send outstanding.

• Seal the public types. Channel, SelectCases, TaskScope, CancelToken, ChannelClosedError and CancelledException are now final. None is meant to be subtyped — a channel's guarantees come from its implementation, not from an interface — and doing this now, while the package is young, keeps every future field from being a breaking change for a subclasser later. Nothing in the package, its tests, its example or its benchmark subtypes any of them. No behaviour change.

First pub.dev release. The package was developed under the name channels, which pub.dev rejects as too similar to the existing channel package, so it is published as go_channels. The import is package:go_channels/go_channels.dart; the API is unchanged.

• Add a diagram to the README, and declare it as a pub.dev screenshot, showing the one thing that separates an unbuffered channel from a buffered one: when send completes. Unbuffered rendezvous — send finishes at the receive; buffered lets send return while the buffer has room, and blocks only when it is full.

• Initial release.
• Channel<T>: buffered and unbuffered channels with send, receive, receiveOr (Go-style value, ok), a stream view, and close.
• select: waits on several channel receives/sends at once and runs exactly one, with onDefault (non-blocking) and onTimeout branches; random choice among ready branches for fairness.
• Structured concurrency: withTaskScope and waitAll run a group of tasks fail-fast, CancelToken provides cooperative cancellation, and withTimeout cancels on a deadline.