Note: This document covers API impact only. For more details, see the ABI compatibility page
Add a protocol event
Overview
- | init | step 1 | step 2 | step 3 | step 4 |
---|---|---|---|---|---|
fidl | link | link | link | ||
dart | link | link | |||
go | link | link | |||
hlcpp | link | link | |||
llcpp | link | link | |||
rust | link | link | link |
Initial State {#init}
FIDL {#fidl-init}
protocol Example {
-> OnExistingEvent();
};
Dart {#dart-init}
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}
func expectEvents(c *lib.ExampleWithCtxInterface) {
_ = c.ExpectOnExistingEvent(context.Background())
}
func sendEvents(p *lib.ExampleEventProxy) {
_ = p.OnExistingEvent()
}
HLCPP {#hlcpp-init}
void expectEvents(fidl_test::ExamplePtr* client) {
client->events().OnExistingEvent = []() {};
}
void sendEvents(fidl::Binding<fidl_test::Example>* server) { server->events().OnExistingEvent(); }
LLCPP {#llcpp-init}
class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
};
class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
};
void sendEvents(fidl::ServerBindingRef<fidl_test::Example> server) { server->OnExistingEvent(); }
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()?;
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
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.
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.
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.
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.
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.
class AsyncEventHandler : public fidl::WireAsyncEventHandler<fidl_test::Example> {
void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
+ void OnNewEvent(fidl_test::Example::OnNewEventResponse* event) override {}
};
class SyncEventHandler : public fidl::WireSyncEventHandler<fidl_test::Example> {
void OnExistingEvent(fidl_test::Example::OnExistingEventResponse* event) override {}
+ void OnNewEvent(fidl_test::Example::OnNewEventResponse* 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.
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.
protocol Example {
-> OnExistingEvent();
- [Transitional]
-> OnNewEvent();
};