Note: This document covers API impact only. For more details, see the ABI compatibility page

Remove a protocol event

Overview

Initial State {#init}

FIDL {#fidl-init}

protocol Example {
    -> OnExistingEvent();
    -> OnOldEvent();
};

Dart {#dart-init}

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

Go {#go-init}

func expectEvents(c *lib.ExampleWithCtxInterface) {
    _ = c.ExpectOnExistingEvent(context.Background())
    _ = c.ExpectOnOldEvent(context.Background())
}
func sendEvents(p *lib.ExampleEventProxy) {
    _ = p.OnExistingEvent()
    _ = p.OnOldEvent()
}

HLCPP {#hlcpp-init}

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

LLCPP {#llcpp-init}

class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
  void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
  void OnOldEvent(fidl_test::Example::OnOldEventResponse* event) override {}
};
class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
  void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
  void OnOldEvent(fidl_test::Example::OnOldEventResponse* event) override {}
};
void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) {
  server->OnExistingEvent();
  server->OnOldEvent();
}

Rust {#rust-init}

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_old_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 { .. } => {}
            fidl_lib::ExampleEvent::OnOldEvent { .. } => {}
        }
    }
    Ok(())
}

Update FIDL Library {#step-1}

• Mark the method that is being removed with the [Transitional] attribute.

  protocol Example {
      -> OnExistingEvent();
+     [Transitional]
      -> OnOldEvent();
  };

Update Source Code {#step-2}

Dart {#dart-2}

• Remove implementations of the event stream
• Stop handling the event on the client side.

  class Server extends fidllib.Example {
    final _onExistingEventStreamController = StreamController<void>();
-   final _onOldEventStreamController = StreamController<void>();
    @override
    Stream<void> get onExistingEvent => _onExistingEventStreamController.stream;
- 
-   @override
-   Stream<void> get onOldEvent => _onOldEventStreamController.stream;
  }
  void expectEvents(fidllib.ExampleProxy client) async {
    await client.onExistingEvent.first;
-   await client.onOldEvent.first;
  }

Go {#go-2}

• Remove usages of the event.

  func expectEvents(c *lib.ExampleWithCtxInterface) {
      _ = c.ExpectOnExistingEvent(context.Background())
-     _ = c.ExpectOnOldEvent(context.Background())
  }
  func sendEvents(p *lib.ExampleEventProxy) {
      _ = p.OnExistingEvent()
-     _ = p.OnOldEvent()
  }

HLCPP {#hlcpp-2}

• Remove any uses of the event being removed.

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

LLCPP {#llcpp-2}

• Remove any uses of the event being removed.

  class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
    void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
-   void OnOldEvent(fidl_test::Example::OnOldEventResponse* event) override {}
  };
  class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
    void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
-   void OnOldEvent(fidl_test::Example::OnOldEventResponse* event) override {}
  };
- void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) {
-   server->OnExistingEvent();
-   server->OnOldEvent();
- }
+ void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) { server->OnExistingEvent(); }

Rust {#rust-2}

• Add #[allow(unreachable_patterns)] to any client event stream match statements, and replace the arm for the event being removed with a catch-all (_) arm.
• Servers should stop sending the event.

  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_old_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::OnOldEvent { .. } => {}
+             _ => {}
          }
      }
      Ok(())
  }

Update FIDL Library {#step-3}

• Remove the [Transitional] attribute.

  protocol Example {
      -> OnExistingEvent();
-     [Transitional]
-     -> OnOldEvent();
  };

Update Source Code {#step-4}

Rust {#rust-4}

• Remove #[allow(unreachable_patterns)] and the catch-all arm.

  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(())
  }