oneshot

Documentation

Overview

Package oneshot provides a single-value, single-delivery channel.

Exactly one Send will ever succeed and the value is delivered to exactly one Recv. New hands out a sender and a receiver; each side is closed via its own Sender.Close / Receiver.Close. Either side may cancel by closing its handle, and the other side observes gochan.ErrClosed on its next operation.

Typical uses

Returning a single result from a goroutine, request/response RPC-style handoff, "done" signalling with an attached value.

Semantics

Single delivery. After one successful Send/Recv pair, both sides are spent. Subsequent Send returns gochan.ErrClosed; subsequent Recv returns gochan.ErrClosed.

Cancellation. Either side may Close to abandon the exchange. The other side observes gochan.ErrClosed on its next operation. Send returning nil means the value was accepted into the slot, not that a Recv has observed it — Send does not block on a receiver. If the receiver closes before consuming, the value is silently dropped and the receiver's next Recv returns gochan.ErrClosed. Send only returns ErrClosed when the pair was already terminal at the moment Send acquired the slot lock.

No goroutine leak. Because Send does not block on a receiver, a sender that completes its work and then has its receiver vanish never leaks. Conversely, a Recv caller that wants to bail must use Receiver.RecvContext or Receiver.Close.

Index

• func New[T any]() (*Sender[T], *Receiver[T])
• type Receiver
  • func (rx *Receiver[T]) Chan() <-chan T
  • func (rx *Receiver[T]) Close()
  • func (rx *Receiver[T]) Recv() (T, error)
  • func (rx *Receiver[T]) RecvContext(ctx context.Context) (T, error)
  • func (rx *Receiver[T]) TryRecv() (T, error)
• type Sender
  • func (tx *Sender[T]) Close()
  • func (tx *Sender[T]) Send(v T) error
  • func (tx *Sender[T]) SendContext(ctx context.Context, v T) error
  • func (tx *Sender[T]) TrySend(v T) error

Functions

func New

func New[T any]() (*Sender[T], *Receiver[T])

New creates a fresh oneshot pair: a sender and a receiver. Each side is closed independently via Sender.Close / Receiver.Close; both are idempotent.

Types

type Receiver

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

Receiver is the receive-side handle of a oneshot pair.

func (*Receiver[T]) Chan

func (rx *Receiver[T]) Chan() <-chan T

Chan returns a native channel that yields the value once and is then closed, or closes empty if the pair is cancelled before a successful Send. Useful in a select. Repeated calls return the same channel.

If Chan is used, the value is delivered there and a subsequent Recv on the same receiver returns gochan.ErrClosed — pick one consumption mechanism per receiver.

func (*Receiver[T]) Close

func (rx *Receiver[T]) Close()

Close cancels the channel from the receiver side. Idempotent.

func (*Receiver[T]) Recv

func (rx *Receiver[T]) Recv() (T, error)

Recv blocks until the value is sent. Returns gochan.ErrClosed if the sender closes without sending, or if the value has already been consumed.

func (*Receiver[T]) RecvContext

func (rx *Receiver[T]) RecvContext(ctx context.Context) (T, error)

RecvContext blocks until the value is sent or ctx is cancelled. Cancelling the context does not close the receiver.

func (*Receiver[T]) TryRecv

func (rx *Receiver[T]) TryRecv() (T, error)

TryRecv is non-blocking. Returns the value if already sent, gochan.ErrEmpty if not yet sent, or gochan.ErrClosed if closed or already consumed.

type Sender

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

Sender is the send-side handle of a oneshot pair.

func (*Sender[T]) Close

func (tx *Sender[T]) Close()

Close cancels the channel from the sender side. Idempotent; a no-op after a successful Send.

func (*Sender[T]) Send

func (tx *Sender[T]) Send(v T) error

Send deposits v into the slot and returns immediately without waiting for a receiver. Returns gochan.ErrClosed if the pair is already terminated at the moment Send acquires the slot lock. A nil return means the value was accepted into the slot; a concurrent Receiver.Close that wins the race after Send commits may still drop the value before any Recv observes it (see the package overview).

func (*Sender[T]) SendContext

func (tx *Sender[T]) SendContext(ctx context.Context, v T) error

SendContext returns ctx.Err() if ctx is already cancelled; otherwise it behaves like Send. Send never blocks, so there is nothing for cancellation to interrupt mid-call.

func (*Sender[T]) TrySend

func (tx *Sender[T]) TrySend(v T) error

TrySend is equivalent to Send: oneshot Send never blocks.