summaryrefslogtreecommitdiff
path: root/events/docs/events.md
diff options
context:
space:
mode:
Diffstat (limited to 'events/docs/events.md')
-rw-r--r--events/docs/events.md136
1 files changed, 0 insertions, 136 deletions
diff --git a/events/docs/events.md b/events/docs/events.md
deleted file mode 100644
index 37059b25..00000000
--- a/events/docs/events.md
+++ /dev/null
@@ -1,136 +0,0 @@
-## RoadRunner Events bus
-
-RR events bus might be useful when one plugin raises some event on which another plugin should react. For example,
-plugins like sentry might log errors from the `http` plugin.
-
-## Simple subscription
-
-Events bus supports wildcard subscriptions on the events as well as the direct subscriptions on the particular event.
-
-Let's have a look at the simple example:
-
-```go
-package foo
-
-import (
- "github.com/spiral/roadrunner/v2/events"
-)
-
-func foo() {
- eh, id := events.Bus()
- defer eh.Unsubscribe(id)
-
- ch := make(chan events.Event, 100)
- err := eh.SubscribeP(id, "http.EventJobOK", ch)
- if err != nil {
- panic(err)
- }
-
- eh.Send(events.NewEvent(events.EventJobOK, "http", "foo"))
- evt := <-ch
- // evt.Message() -> "foo"
- // evt.Plugin() -> "http"
- // evt.Type().String() -> "EventJobOK"
-}
-```
-
-Here:
-1. `eh, id := events.Bus()` get the instance (it's global) of the events bus. Make sure to unsubscribe event handler when you don't need it anymore: `eh.Unsubscribe(id)`.
-2. `ch := make(chan events.Event, 100)` create an events channel.
-3. `err := eh.SubscribeP(id, "http.EventJobOK", ch)` subscribe to the events which fits your pattern (`http.EventJobOK`).
-4. `eh.Send(events.NewEvent(events.EventJobOK, "http", "foo"))` emit event from the any plugin.
-5. `evt := <-ch` get the event.
-
-Notes:
-1. If you use only `eh.Send` events bus function, you don't need to unsubscribe, so, you may simplify the declaration to the `eh, _ := events.Bus()`.
-
-## Wildcards
-
-As mentioned before, RR events bus supports wildcards subscriptions, like: `*.SomeEvent`, `http.*`, `http.Some*`, `*`.
-Let's have a look at the next sample of code:
-
-```go
-package foo
-
-import (
- "github.com/spiral/roadrunner/v2/events"
-)
-
-func foo() {
- eh, id := events.Bus()
- defer eh.Unsubscribe(id)
-
- ch := make(chan events.Event, 100)
- err := eh.SubscribeP(id, "http.*", ch)
- if err != nil {
- panic(err)
- }
-
- eh.Send(events.NewEvent(events.EventJobOK, "http", "foo"))
- evt := <-ch
- // evt.Message() -> "foo"
- // evt.Plugin() -> "http"
- // evt.Type().String() -> "EventJobOK"
-}
-```
-
-One change between these samples is in the `SubscribeP` pattern: `err := eh.SubscribeP(id, "http.*", ch)`. Here we used `http.*` instead of `http.EventJobOK`.
-
-You also have the access to the event message, plugin and type. Message is a custom, user-defined message to log or to show to the subscriber. Plugin is a source plugin who raised this event. And the event type - is your custom or RR event type.
-
-
-## How to implement custom event
-
-Event type is a `fmt.Stringer`. That means, that your custom event type should implement this interface. Let's have a look at how to do that:
-
-```go
-package foo
-
-type MySuperEvent uint32
-
-const (
- EventHTTPError MySuperEvent = iota
-)
-
-func (mse MySuperEvent) String() string {
- switch mse {
- case EventHTTPError:
- return "EventHTTPError"
- default:
- return "UnknownEventType"
- }
-}
-```
-
-Here we defined a custom type - `MySuperEvent`. For sure, it might have any name you want and represent for example some domain field like `WorkersPoolEvent` represents RR sync.pool events. Then you need to implement a `fmt.Stringer` on your custom event type.
-Next you need to create an enum with the actual events and that's it.
-
-How to use that:
-```go
-package foo
-
-import (
- "github.com/spiral/roadrunner/v2/events"
-)
-
-func foo() {
- eh, id := events.Bus()
- defer eh.Unsubscribe(id)
-
- ch := make(chan events.Event, 100)
- err := eh.SubscribeP(id, "http.EventHTTPError", ch)
- if err != nil {
- panic(err)
- }
-
- // first arg of the NewEvent method is fmt.Stringer
- eh.Send(events.NewEvent(EventHTTPError, "http", "foo"))
- evt := <-ch
- // evt.Message() -> "foo"
- // evt.Plugin() -> "http"
- // evt.Type().String() -> "EventHTTPError"
-}
-```
-
-Important note: you don't need to import your custom event types into the subscriber. You only need to know the name of that event and pass a string to the subscriber.
-