handler

Documentation

Overview

Package handler handles incoming Gateway events. It reflects the function's first argument and caches that for use in each event.

Performance

Each call to the event would take 167 ns/op for roughly each handler. Scaling that up to 100 handlers is roughly the same as multiplying 167 ns by 100, which gives 16700 ns or 0.0167 ms.

BenchmarkReflect-8  7260909  167 ns/op

Usage

Handler's usage is mostly similar to Discordgo, in that AddHandler expects a function with only one argument or an event channel. For more information, refer to AddHandler.

Index

• type Handler
  • func New() *Handler
  • func (h *Handler) AddHandler(handler interface{}) (rm func())
  • func (h *Handler) AddHandlerCheck(handler interface{}) (rm func(), err error)
  • func (h *Handler) Call(ev interface{})
  • func (h *Handler) CallDirect(ev interface{})
  • func (h *Handler) ChanFor(fn func(interface{}) bool) (out <-chan interface{}, cancel func())
  • func (h *Handler) WaitFor(ctx context.Context, fn func(interface{}) bool) interface{}

Types

type Handler

type Handler struct {
	// Synchronous controls whether to spawn each event handler in its own
	// goroutine. Default false (meaning goroutines are spawned).
	Synchronous bool
	// contains filtered or unexported fields
}

func New

func New() *Handler

func (*Handler) AddHandler

func (h *Handler) AddHandler(handler interface{}) (rm func())

AddHandler adds the handler, returning a function that would remove this handler when called. A handler type is either a single-argument no-return function or a channel.

Function

A handler can be a function with a single argument that is the expected event type. It must not have any returns or any other number of arguments.

// An example of a valid function handler.
h.AddHandler(func(*gateway.MessageCreateEvent) {})

Channel

A handler can also be a channel. The underlying type that the channel wraps around will be the event type. As such, the type rules are the same as function handlers.

Keep in mind that the user must NOT close the channel. In fact, the channel should not be closed at all. The caller function WILL PANIC if the channel is closed!

When the rm callback that is returned is called, it will also guarantee that all blocking sends will be cancelled. This helps prevent dangling goroutines.

// An example of a valid channel handler.
ch := make(chan *gateway.MessageCreateEvent)
h.AddHandler(ch)

func (*Handler) AddHandlerCheck

func (h *Handler) AddHandlerCheck(handler interface{}) (rm func(), err error)

AddHandlerCheck adds the handler, but safe-guards reflect panics with a recoverer, returning the error. Refer to AddHandler for more information.

func (*Handler) Call

func (h *Handler) Call(ev interface{})

Call calls all handlers with the given event. This is an internal method; use with care.

func (*Handler) CallDirect

func (h *Handler) CallDirect(ev interface{})

CallDirect is the same as Call, but only calls those event handlers that listen for this specific event, i.e. that aren't interface handlers.

func (*Handler) ChanFor

func (h *Handler) ChanFor(fn func(interface{}) bool) (out <-chan interface{}, cancel func())

ChanFor returns a channel that would receive all incoming events that match the callback given. The cancel() function removes the handler and drops all hanging goroutines.

This method is more intended to be used as a filter. For a persistent event channel, consider adding it directly as a handler with AddHandler.

func (*Handler) WaitFor

func (h *Handler) WaitFor(ctx context.Context, fn func(interface{}) bool) interface{}

WaitFor blocks until there's an event. It's advised to use ChanFor instead, as WaitFor may skip some events if it's not ran fast enough after the event arrived.