1EventBus
2======
3
4[![GoDoc](https://godoc.org/github.com/asaskevich/EventBus?status.svg)](https://godoc.org/github.com/asaskevich/EventBus) [![Coverage Status](https://img.shields.io/coveralls/asaskevich/EventBus.svg)](https://coveralls.io/r/asaskevich/EventBus?branch=master) [![Build Status](https://travis-ci.org/asaskevich/EventBus.svg)](https://travis-ci.org/asaskevich/EventBus)
5
6Package EventBus is the little and lightweight eventbus with async compatibility for GoLang.
7
8#### Installation
9Make sure that Go is installed on your computer.
10Type the following command in your terminal:
11
12	go get github.com/asaskevich/EventBus
13
14After it the package is ready to use.
15
16#### Import package in your project
17Add following line in your `*.go` file:
18```go
19import "github.com/asaskevich/EventBus"
20```
21If you unhappy to use long `EventBus`, you can do something like this:
22```go
23import (
24	evbus "github.com/asaskevich/EventBus"
25)
26```
27
28#### Example
29```go
30func calculator(a int, b int) {
31	fmt.Printf("%d\n", a + b)
32}
33
34func main() {
35	bus := EventBus.New();
36	bus.Subscribe("main:calculator", calculator);
37	bus.Publish("main:calculator", 20, 40);
38	bus.Unsubscribe("main:calculator", calculator);
39}
40```
41
42#### Implemented methods
43* **New()**
44* **Subscribe()**
45* **SubscribeOnce()**
46* **HasCallback()**
47* **Unsubscribe()**
48* **Publish()**
49* **SubscribeAsync()**
50* **SubscribeOnceAsync()**
51* **WaitAsync()**
52
53#### New()
54New returns new EventBus with empty handlers.
55```go
56bus := EventBus.New();
57```
58
59#### Subscribe(topic string, fn interface{}) error
60Subscribe to a topic. Returns error if `fn` is not a function.
61```go
62func Handler() { ... }
63...
64bus.Subscribe("topic:handler", Handler)
65```
66
67#### SubscribeOnce(topic string, fn interface{}) error
68Subscribe to a topic once. Handler will be removed after executing. Returns error if `fn` is not a function.
69```go
70func HelloWorld() { ... }
71...
72bus.SubscribeOnce("topic:handler", HelloWorld)
73```
74
75#### Unsubscribe(topic string, fn interface{}) error
76Remove callback defined for a topic. Returns error if there are no callbacks subscribed to the topic.
77```go
78bus.Unsubscribe("topic:handler", HelloWord);
79```
80
81#### HasCallback(topic string) bool
82Returns true if exists any callback subscribed to the topic.
83
84#### Publish(topic string, args ...interface{})
85Publish executes callback defined for a topic. Any additional argument will be transferred to the callback.
86```go
87func Handler(str string) { ... }
88...
89bus.Subscribe("topic:handler", Handler)
90...
91bus.Publish("topic:handler", "Hello, World!");
92```
93
94#### SubscribeAsync(topic string, fn interface{}, transactional bool)
95Subscribe to a topic with an asynchronous callback. Returns error if `fn` is not a function.
96```go
97func slowCalculator(a, b int) {
98	time.Sleep(3 * time.Second)
99	fmt.Printf("%d\n", a + b)
100}
101
102bus := EventBus.New()
103bus.SubscribeAsync("main:slow_calculator", slowCalculator, false)
104
105bus.Publish("main:slow_calculator", 20, 60)
106
107fmt.Println("start: do some stuff while waiting for a result")
108fmt.Println("end: do some stuff while waiting for a result")
109
110bus.WaitAsync() // wait for all async callbacks to complete
111
112fmt.Println("do some stuff after waiting for result")
113```
114Transactional determines whether subsequent callbacks for a topic are run serially (true) or concurrently(false)
115
116#### SubscribeOnceAsync(topic string, args ...interface{})
117SubscribeOnceAsync works like SubscribeOnce except the callback to executed asynchronously
118
119####  WaitAsync()
120WaitAsync waits for all async callbacks to complete.
121
122#### Cross Process Events
123Works with two rpc services:
124- a client service to listen to remotely published events from a server
125- a server service to listen to client subscriptions
126
127server.go
128```go
129func main() {
130    server := NewServer(":2010", "/_server_bus_", New())
131    server.Start()
132    // ...
133    server.EventBus().Publish("main:calculator", 4, 6)
134    // ...
135    server.Stop()
136}
137```
138
139client.go
140```go
141func main() {
142    client := NewClient(":2015", "/_client_bus_", New())
143    client.Start()
144    client.Subscribe("main:calculator", calculator, ":2010", "/_server_bus_")
145    // ...
146    client.Stop()
147}
148```
149
150#### Notes
151Documentation is available here: [godoc.org](https://godoc.org/github.com/asaskevich/EventBus).
152Full information about code coverage is also available here: [EventBus on gocover.io](http://gocover.io/github.com/asaskevich/EventBus).
153
154#### Support
155If you do have a contribution for the package feel free to put up a Pull Request or open Issue.
156
157#### Special thanks to [contributors](https://github.com/asaskevich/EventBus/graphs/contributors)
158* [Brian Downs](https://github.com/briandowns)
159* [Dominik Schulz](https://github.com/gittex)
160* [bennAH](https://github.com/bennAH)
161* [John Noble] (https://github.com/gaxunil)
162* [Evan Borgstrom] (https://github.com/borgstrom)
163