github.com/chain5j/chain5j-pkg@v1.0.7/eventbus/README.md (about)

     1  EventBus
     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  
     6  Package EventBus is the little and lightweight eventbus with async compatibility for GoLang.
     7  
     8  #### Installation
     9  Make sure that Go is installed on your computer.
    10  Type the following command in your terminal:
    11  
    12  	go get github.com/asaskevich/EventBus
    13  
    14  After it the package is ready to use.
    15  
    16  #### Import package in your project
    17  Add following line in your `*.go` file:
    18  ```go
    19  import "github.com/asaskevich/EventBus"
    20  ```
    21  If you unhappy to use long `EventBus`, you can do something like this:
    22  ```go
    23  import (
    24  	evbus "github.com/asaskevich/EventBus"
    25  )
    26  ```
    27  
    28  #### Example
    29  ```go
    30  func calculator(a int, b int) {
    31  	fmt.Printf("%d\n", a + b)
    32  }
    33  
    34  func 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()
    54  New returns new EventBus with empty handlers.
    55  ```go
    56  bus := EventBus.New();
    57  ```
    58  
    59  #### Subscribe(topic string, fn interface{}) error
    60  Subscribe to a topic. Returns error if `fn` is not a function.
    61  ```go
    62  func Handler() { ... }
    63  ...
    64  bus.Subscribe("topic:handler", Handler)
    65  ```
    66  
    67  #### SubscribeOnce(topic string, fn interface{}) error
    68  Subscribe to a topic once. Handler will be removed after executing. Returns error if `fn` is not a function.
    69  ```go
    70  func HelloWorld() { ... }
    71  ...
    72  bus.SubscribeOnce("topic:handler", HelloWorld)
    73  ```
    74  
    75  #### Unsubscribe(topic string, fn interface{}) error
    76  Remove callback defined for a topic. Returns error if there are no callbacks subscribed to the topic.
    77  ```go
    78  bus.Unsubscribe("topic:handler", HelloWord);
    79  ```
    80  
    81  #### HasCallback(topic string) bool
    82  Returns true if exists any callback subscribed to the topic.
    83  
    84  #### Publish(topic string, args ...interface{})
    85  Publish executes callback defined for a topic. Any additional argument will be transferred to the callback.
    86  ```go
    87  func Handler(str string) { ... }
    88  ...
    89  bus.Subscribe("topic:handler", Handler)
    90  ...
    91  bus.Publish("topic:handler", "Hello, World!");
    92  ```
    93  
    94  #### SubscribeAsync(topic string, fn interface{}, transactional bool)
    95  Subscribe to a topic with an asynchronous callback. Returns error if `fn` is not a function.
    96  ```go
    97  func slowCalculator(a, b int) {
    98  	time.Sleep(3 * time.Second)
    99  	fmt.Printf("%d\n", a + b)
   100  }
   101  
   102  bus := EventBus.New()
   103  bus.SubscribeAsync("main:slow_calculator", slowCalculator, false)
   104  
   105  bus.Publish("main:slow_calculator", 20, 60)
   106  
   107  fmt.Println("start: do some stuff while waiting for a result")
   108  fmt.Println("end: do some stuff while waiting for a result")
   109  
   110  bus.WaitAsync() // wait for all async callbacks to complete
   111  
   112  fmt.Println("do some stuff after waiting for result")
   113  ```
   114  Transactional determines whether subsequent callbacks for a topic are run serially (true) or concurrently(false)
   115  
   116  #### SubscribeOnceAsync(topic string, args ...interface{})
   117  SubscribeOnceAsync works like SubscribeOnce except the callback to executed asynchronously
   118  
   119  ####  WaitAsync()
   120  WaitAsync waits for all async callbacks to complete.
   121  
   122  #### Cross Process Events
   123  Works 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  
   127  server.go
   128  ```go
   129  func 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  
   139  client.go
   140  ```go
   141  func 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
   151  Documentation is available here: [godoc.org](https://godoc.org/github.com/asaskevich/EventBus).
   152  Full information about code coverage is also available here: [EventBus on gocover.io](http://gocover.io/github.com/asaskevich/EventBus).
   153  
   154  #### Support
   155  If 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)