1package event
2
3import (
4	"io"
5	"reflect"
6)
7
8// SubscriptionOpt represents a subscriber option. Use the options exposed by the implementation of choice.
9type SubscriptionOpt = func(interface{}) error
10
11// EmitterOpt represents an emitter option. Use the options exposed by the implementation of choice.
12type EmitterOpt = func(interface{}) error
13
14// CancelFunc closes a subscriber.
15type CancelFunc = func()
16
17// wildcardSubscriptionType is a virtual type to represent wildcard
18// subscriptions.
19type wildcardSubscriptionType interface{}
20
21// WildcardSubscription is the type to subscribe to to receive all events
22// emitted in the eventbus.
23var WildcardSubscription = new(wildcardSubscriptionType)
24
25// Emitter represents an actor that emits events onto the eventbus.
26type Emitter interface {
27	io.Closer
28
29	// Emit emits an event onto the eventbus. If any channel subscribed to the topic is blocked,
30	// calls to Emit will block.
31	//
32	// Calling this function with wrong event type will cause a panic.
33	Emit(evt interface{}) error
34}
35
36// Subscription represents a subscription to one or multiple event types.
37type Subscription interface {
38	io.Closer
39
40	// Out returns the channel from which to consume events.
41	Out() <-chan interface{}
42}
43
44// Bus is an interface for a type-based event delivery system.
45type Bus interface {
46	// Subscribe creates a new Subscription.
47	//
48	// eventType can be either a pointer to a single event type, or a slice of pointers to
49	// subscribe to multiple event types at once, under a single subscription (and channel).
50	//
51	// Failing to drain the channel may cause publishers to block.
52	//
53	// If you want to subscribe to ALL events emitted in the bus, use
54	// `WildcardSubscription` as the `eventType`:
55	//
56	//  eventbus.Subscribe(WildcardSubscription)
57	//
58	// Simple example
59	//
60	//  sub, err := eventbus.Subscribe(new(EventType))
61	//  defer sub.Close()
62	//  for e := range sub.Out() {
63	//    event := e.(EventType) // guaranteed safe
64	//    [...]
65	//  }
66	//
67	// Multi-type example
68	//
69	//  sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
70	//  defer sub.Close()
71	//  for e := range sub.Out() {
72	//    select e.(type):
73	//      case EventA:
74	//        [...]
75	//      case EventB:
76	//        [...]
77	//    }
78	//  }
79	Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)
80
81	// Emitter creates a new event emitter.
82	//
83	// eventType accepts typed nil pointers, and uses the type information for wiring purposes.
84	//
85	// Example:
86	//  em, err := eventbus.Emitter(new(EventT))
87	//  defer em.Close() // MUST call this after being done with the emitter
88	//  em.Emit(EventT{})
89	Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)
90
91	// GetAllEventTypes returns all the event types that this bus knows about
92	// (having emitters and subscribers). It omits the WildcardSubscription.
93	//
94	// The caller is guaranteed that this function will only return value types;
95	// no pointer types will be returned.
96	GetAllEventTypes() []reflect.Type
97}
98