fx-callback 1.0.2

A subscription based callback to inform subscribers about relevant data events within structs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# FX-Callback
![Build](https://github.com/yoep/fx-callback/workflows/Build/badge.svg)
![Version](https://img.shields.io/github/v/tag/yoep/fx-callback?label=version)
[![Crates](https://img.shields.io/crates/v/fx-callback)](https://crates.io/crates/fx-callback)
[![License: Apache-2.0](https://img.shields.io/github/license/yoep/fx-callback)](./LICENSE)
[![codecov](https://codecov.io/gh/yoep/fx-callback/branch/master/graph/badge.svg?token=A801IOOZAH)](https://codecov.io/gh/yoep/fx-callback)

A subscription based callback for data events that might occur within one or more structs.
It is mainly used within the FX landscape to allow events to be published between multiple structs.

## Example

```rust
use fx_callback::{Callback, MultiThreadedCallback, Subscriber, Subscription};

/// The events of the struct that informs subscribers about changes to the data within the struct.
#[derive(Debug, Clone, PartialEq)]
enum MyEvent {
    Foo,
}

/// The struct to which an interested subscriber can subscribe to.
#[derive(Debug)]
struct Example {
    callbacks: MultiThreadedCallback<MyEvent>,
}

impl Example {
    fn invoke_event(&self) {
        self.callbacks.invoke(MyEvent::Foo);
    }
}

impl Callback<MyEvent> for Example {
    fn subscribe(&self) -> Subscription<MyEvent> {
        self.callbacks.subscribe()
    }

    fn subscribe_with(&self, subscriber: Subscriber<MyEvent>) {
        self.callbacks.subscribe_with(subscriber)
    }
}
```

## Usage

### Subscription/event holder

To get started with adding callbacks to your structs, add one of the implementations of the `Callback` trait.
Make sure that the struct implements the `Debug` trait.

```rust
use fx_callback::{Callback, MultiThreadedCallback};

#[derive(Debug)]
pub struct MyStruct {
    callbacks: MultiThreadedCallback<MyEvent>,
}
```

Add the `Callback` trait implementation to your struct to allow adding callbacks.

```rust
impl Callback<MyEvent> for MyStruct {
    fn subscribe(&self) -> Subscription<MyEvent> {
        self.callbacks.subscribe()
    }
    
    fn subscribe_with(&self, subscriber: Subscriber<MyEvent>) {
        self.callbacks.subscribe_with(subscriber)
    }
}
```

When you want to inform subscribers about a certain event, call the `invoke` method.

```rust
impl MyStruct {
    pub fn invoke_event(&self) {
        self.callbacks.invoke(MyEvent::Foo);
    }
}
```

### Subscriber

The interested subscriber can subscribe to the interested event of a struct that implements the `Callback` trait.

```rust
use fx_callback::{Callback, MultiThreadedCallback, Subscriber, Subscription};
use tokio::runtime::Runtime;

fn main() {
    let runtime = Runtime::new().unwrap();
    let struct_with_callback = MyStruct::new();
    
    let mut receiver = struct_with_callback.subscribe();
    runtime.spawn(async move {
       loop {
           if let Some(event) = receiver.recv().await {
               println!("Received event: {}", event);
           } else {
               break;
           }
       } 
    });

    struct_with_callback.invoke_event();
}
```