blstr

Documentation

Overview

Package blstr (blaster? blast string?) is an ill-named library for easily setting up best-effort broadcast communication between goroutines.

Synchronization and consistency is traded for speed and predictability of send operations.

The best use case is where perfect consistency may not be necessary and some message loss on slow receivers is more tolerable than choking upstream senders.

Index

• type ByteHub
  • func New() *ByteHub
  • func (bh *ByteHub) Count() int
  • func (bh *ByteHub) Flood(from int, msg []byte) (skipped int)
  • func (bh *ByteHub) Reset()
  • func (bh *ByteHub) Send(to int, msg []byte) (err error)
  • func (bh *ByteHub) Subscribe(id int, ch chan<- []byte) error
  • func (bh *ByteHub) Unsubscribe(id int)

Types

type ByteHub

type ByteHub struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ByteHub implements a multiuser communication channel.

func New

func New() *ByteHub

New returns a new ByteHub

func (*ByteHub) Count

func (bh *ByteHub) Count() int

Count returns the current number of subscriptions to the hub.

func (*ByteHub) Flood

func (bh *ByteHub) Flood(from int, msg []byte) (skipped int)

Flood provides broadcast communication over the hub.

All listening subscribers will receive the message provided. The from field is usually set with the sender ID to be excluded from the broadcast. This allows subscribers to send without having to filter out their own messages.

A count of skipped subscribers (excluding the sender) that are unable to receive the message is returned.

func (*ByteHub) Reset

func (bh *ByteHub) Reset()

Reset removes all subscriptions from the hub and allows it to be reused.

func (*ByteHub) Send

func (bh *ByteHub) Send(to int, msg []byte) (err error)

Send provides unicast communication over the hub.

An attempt is made to send a message to the specified subscriber. Errors are returned if the subscriber could not be found or is unable to receive the message.

func (*ByteHub) Subscribe

func (bh *ByteHub) Subscribe(id int, ch chan<- []byte) error

Subscribe to be notified when broadcast events occur on the hub.

Messages can be dropped if receiver stops listening, or if messages arrive faster than they can be consumed. Channels can be buffered to mitigate this to some extent.

func (*ByteHub) Unsubscribe

func (bh *ByteHub) Unsubscribe(id int)

Unsubscribe tries to remove the subscription by ID if it exists.