docs/development/languages/fidl/guides/compatibility/protocol_event_add.md

<!-- WARNING: This file is machine generated by //src/tests/fidl/source_compatibility/gen, do not edit. -->

Note: This document covers API impact only. For more details, see the
[ABI compatibility page](/docs/development/languages/fidl/guides/compatibility/README.md)

# Add a protocol event

## Overview

-|[init](#init)|[step 1](#step-1)|[step 2](#step-2)|[step 3](#step-3)|[step 4](#step-4)
---|---|---|---|---|---
fidl|[link](#fidl-init)||[link](#fidl-2)||[link](#fidl-4)
dart|[link](#dart-init)|||[link](#dart-3)|
go|[link](#go-init)|||[link](#go-3)|
hlcpp|[link](#hlcpp-init)|||[link](#hlcpp-3)|
llcpp|[link](#llcpp-init)|||[link](#llcpp-3)|
rust|[link](#rust-init)|[link](#rust-1)||[link](#rust-3)|

## Initial State {#init}

### FIDL {#fidl-init}

```fidl
protocol Example {
    -> OnExistingEvent();
};
```

### Dart {#dart-init}

```dart
class Server extends fidllib.Example {
  final _onExistingEventStreamController = StreamController<void>();

  @override
  Stream<void> get onExistingEvent => _onExistingEventStreamController.stream;
}

void expectEvents(fidllib.ExampleProxy client) async {
  await client.onExistingEvent.first;
}
```

### Go {#go-init}

```go
func expectEvents(c *lib.ExampleWithCtxInterface) {
	_ = c.ExpectOnExistingEvent(context.Background())
}

func sendEvents(p *lib.ExampleEventProxy) {
	_ = p.OnExistingEvent()
}

```

### HLCPP {#hlcpp-init}

```cpp
void expectEvents(fidl_test::ExamplePtr* client) {
  client->events().OnExistingEvent = []() {};
}

void sendEvents(fidl::Binding<fidl_test::Example>* server) { server->events().OnExistingEvent(); }

```

### LLCPP {#llcpp-init}

```cpp
class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
  void OnExistingEvent(fidl::WireResponse<fidl_test::Example::OnExistingEvent>* event) override {}
};

class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
  void OnExistingEvent(fidl::WireResponse<fidl_test::Example::OnExistingEvent>* event) override {}
};

void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) { server->OnExistingEvent(); }
```

### Rust {#rust-init}

```rust
fn send_events(stream: fidl_lib::ExampleRequestStream) -> Result<(), fidl::Error> {
    let control_handle = stream.control_handle();
    control_handle.send_on_existing_event()?;
    Ok(())
}

async fn receive_events(client: fidl_lib::ExampleProxy) -> Result<(), fidl::Error> {
    let mut event_stream = client.take_event_stream();
    while let Some(event) = event_stream.try_next().await? {
        match event {
            fidl_lib::ExampleEvent::OnExistingEvent { .. } => {}
        }
    }
    Ok(())
}
```

## Update Source Code {#step-1}

### Rust {#rust-1}

- Add `#[allow(unreachable_patterns)]` and a catch-all arm (`_`) to any client event stream match statements

```diff
  fn send_events(stream: fidl_lib::ExampleRequestStream) -> Result<(), fidl::Error> {
      let control_handle = stream.control_handle();
      control_handle.send_on_existing_event()?;
      Ok(())
  }
  
  async fn receive_events(client: fidl_lib::ExampleProxy) -> Result<(), fidl::Error> {
      let mut event_stream = client.take_event_stream();
      while let Some(event) = event_stream.try_next().await? {
+         #[allow(unreachable_patterns)]
          match event {
              fidl_lib::ExampleEvent::OnExistingEvent { .. } => {}
+             _ => {}
          }
      }
      Ok(())
  }

```

## Update FIDL Library {#step-2}

- Add the new event and mark it with the `[Transitional]` attribute.

```diff
  protocol Example {
      -> OnExistingEvent();
+     @transitional
+     -> OnNewEvent();
  };

```

## Update Source Code {#step-3}

### Dart {#dart-3}

- Implement the stream for the new event for any server implementations.
- You can start receiving the new event in any clients.

```diff
  class Server extends fidllib.Example {
    final _onExistingEventStreamController = StreamController<void>();
+   final _onNewEventStreamController = StreamController<void>();
  
    @override
    Stream<void> get onExistingEvent => _onExistingEventStreamController.stream;
+ 
+   @override
+   Stream<void> get onNewEvent => _onNewEventStreamController.stream;
  }
  
  void expectEvents(fidllib.ExampleProxy client) async {
    await client.onExistingEvent.first;
+   await client.onNewEvent.first;
  }

```

### Go {#go-3}

- You can start using the new event on both the client and server side.

```diff
  func expectEvents(c *lib.ExampleWithCtxInterface) {
  	_ = c.ExpectOnExistingEvent(context.Background())
+ 	_ = c.ExpectOnNewEvent(context.Background())
  }
  
  func sendEvents(p *lib.ExampleEventProxy) {
  	_ = p.OnExistingEvent()
+ 	_ = p.OnNewEvent()
  }
  

```

### HLCPP {#hlcpp-3}

- You can start using the new event on both the client and server side.

```diff
  void expectEvents(fidl_test::ExamplePtr* client) {
    client->events().OnExistingEvent = []() {};
+   client->events().OnNewEvent = []() {};
  }
  
- void sendEvents(fidl::Binding<fidl_test::Example>* server) { server->events().OnExistingEvent(); }
+ void sendEvents(fidl::Binding<fidl_test::Example>* server) {
+   server->events().OnExistingEvent();
+   server->events().OnNewEvent();
+ }
  

```

### LLCPP {#llcpp-3}

- For usages of the async event handle struct, add a handler for the new event if desired.
- For usages of the async event handler class, you must add a handle for the new event.
- You can start receiving the new event in any clients.

```diff
  class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
    void OnExistingEvent(fidl::WireResponse<fidl_test::Example::OnExistingEvent>* event) override {}
+   void OnNewEvent(fidl::WireResponse<fidl_test::Example::OnNewEvent>* event) override {}
  };
  
  class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
    void OnExistingEvent(fidl::WireResponse<fidl_test::Example::OnExistingEvent>* event) override {}
+   void OnNewEvent(fidl::WireResponse<fidl_test::Example::OnNewEvent>* event) override {}
  };
  
- void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) { server->OnExistingEvent(); }
+ void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) {
+   server->OnExistingEvent();
+   server->OnNewEvent();
+ }

```

### Rust {#rust-3}

- Remove the `#[allow(unreachable_patterns)]` attribute and replace the catch-all arm with the new event.
- You can start sending the new event in any servers.

```diff
  fn send_events(stream: fidl_lib::ExampleRequestStream) -> Result<(), fidl::Error> {
      let control_handle = stream.control_handle();
      control_handle.send_on_existing_event()?;
+     control_handle.send_on_new_event()?;
      Ok(())
  }
  
  async fn receive_events(client: fidl_lib::ExampleProxy) -> Result<(), fidl::Error> {
      let mut event_stream = client.take_event_stream();
      while let Some(event) = event_stream.try_next().await? {
-         #[allow(unreachable_patterns)]
          match event {
              fidl_lib::ExampleEvent::OnExistingEvent { .. } => {}
-             _ => {}
+             fidl_lib::ExampleEvent::OnNewEvent { .. } => {}
          }
      }
      Ok(())
  }

```

## Update FIDL Library {#step-4}

- Remove the `[Transitional]` attribute.

```diff
  protocol Example {
      -> OnExistingEvent();
-     @transitional
      -> OnNewEvent();
  };

```