events.go

// Copyright 2022 Democratized Data Foundation
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

/*
Package events provides the internal event system.
*/
package eventbus

import logging "github.com/ipfs/go-log"

var log = logging.Logger("eventbus")

type Subscription[T any] chan T

// Channel represents a subscribable type that will expose inputted items to subscribers.
type Channel[T any] interface {
	// Subscribe subscribes to the Channel, returning a channel by which events can
	// be read from, or an error should one occur (e.g. if this object is closed).
	//
	// This function is non-blocking unless the subscription-buffer is full.
	Subscribe() (Subscription[T], error)

	// Unsubscribe unsubscribes from the Channel, closing the provided channel.
	//
	// Will do nothing if this object is already closed.
	Unsubscribe(Subscription[T])

	// Publish pushes the given item into this channel. Non-blocking.
	Publish(item T)

	// Close closes this Channel, and any owned or subscribing channels.
	Close()
}

// New creates and returns a new Channel instance.
//
// At the moment this will always return a new simpleChannel, however that may change in
// the future as this feature gets fleshed out.
func New[T any](subscriberBufferSize int, eventBufferSize int) Channel[T] {
	return NewSimpleChannel[T](subscriberBufferSize, eventBufferSize)
}