subq

Documentation

Overview

Package subq abstracts the idea of subscribing to a particular queue so that changes can be immediately notified.

Index

• type SubQ
  • func New() *SubQ
  • func (s *SubQ) Notify(q string)
  • func (s *SubQ) Wait(ctx context.Context, qs []string, pollWait time.Duration, ...) error

Types

type SubQ

type SubQ struct {
	sync.Mutex
	// contains filtered or unexported fields
}

SubQ is a queue subscription service. It is not public, though; it is based on competing consumer principles, like EntroQ itself.

func New

func New() *SubQ

New creates a new queue competing-consumer subscription service.

func (*SubQ) Notify

func (s *SubQ) Notify(q string)

Notify sends notifications to at most one waiting goroutines that something is ready on the given queue. If nobody is listening, it immediately drops the event. This function does not block, but notifies in a new goroutine.

func (*SubQ) Wait

func (s *SubQ) Wait(ctx context.Context, qs []string, pollWait time.Duration, condition func() bool) error

Wait waits on the given queues until something is notified on one or the context expires, whichever comes first. This is the basic behavior when pollWait is 0 and condition is nil.

If condition is not nil, it is called immediately. If it returns true, then the wait is satisfied and the function exits with a nil error. If it returns false, then the function begins to wait for either a notification, a context cancelation, or the expiration of pollWait.

Note that condition should execute quickly and not block. It should test the condition as fast as it can and return. Otherwise "Notify" might busy-wait for a while, which is obviously not good.

When pollWait expires or a suitable notification arrives, condition is called again, and the above process repeats.

If pollWait is 0, the only way to check condition again is if the channel is notified. Otherwise Wait terminates with an error.

This implementation allows you to attempt a polling operation, then wait for notification that the next one is likely to succeed, then check again just in case you got scooped by another process, repeating until something is truly available.

Note that condition is called directly from this function, so if it needs a context, it can simply close over the same one passed in here.