In this example, we start by creating a 2D line-drawing canvas, then proceed to augment its functionality with various data flow patterns commonly used in FIDL, such as implementing flow control on both sides of the connection, and improving performance by reducing the number of message round trips.
Getting started
This baseline case showcases an end-to-end implementation of a simple canvas
using FIDL. This design specifies the Canvas protocol, which allows a client
to add lines to the canvas via the AddLine method, and receive draw updates
from the server via the OnDrawn event.
The protocol we design here will be functional, but suboptimal in terms of both
performance and flow control. For instance, our current "refresh rate" is a
glacial 1 frame per second. What happens if we decide to update at 60 frames per
second (ie, roughly every 16ms, rather than once a second)? Is it possible that
OnDrawn events will overwhelm the client? Conversely, what happens when a
client loads send many AddLine requests at once, perhaps after loading them
from a file? Will the server now be crushed under the load?
This unthrottled implementation is best regarded as a first pass - a relatively simple protocol that demonstrates some functionality, but one that could use some improvement to extract optimal performance, especially under stress.
First, we need to define our interface definitions and test harness. The FIDL, CML, and realm interface definitions set up a scaffold that arbitrary implementations can use:
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.baseline;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add a line to the canvas.
flexible AddLine(struct {
line Line;
});
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
CML
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.baseline.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", the string "PUSH", or the string
// "WAIT". The former builds entries for a call to `AddLines(...)`, "PUSH" makes the
// `AddLines` call, and "WAIT" execution until the next `->OnDrawn(...)` event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; Push, Wait}`
// here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.baseline.Instance" },
],
expose: [
{
protocol: "examples.canvas.baseline.Instance",
from: "self",
},
],
}
Realm
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.baseline.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
Client and server implementations can then be written in any supported language:
Rust
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_baseline::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
for action in config.script.into_iter() {
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
continue;
}
// If the action is not a "WAIT", we need to draw a line instead. Parse the string input,
// making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let line = [from, to];
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
instance.add_line(&line)?;
println!("AddLine request sent: {:?}", line);
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_baseline::{BoundingBox, InstanceRequest, InstanceRequestStream, Point},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
bounding_box: BoundingBox,
}
/// Handler for the `AddLine` method.
fn add_line(state: &mut CanvasState, line: [Point; 2]) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut state.bounding_box;
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
state.changed = true
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change tracker.
state.changed = false
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLine { line, .. } => {
println!("AddLine request received: {:?}", line);
add_line(&mut state_ref.lock().unwrap(), line);
}
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This line will only be reached if the server errors out. The stream will await indefinitely,
// thereby creating a long-lived server. Here, we first wait for the updater task to realize the
// connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (Natural)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.baseline/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/baseline/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_baseline::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::Event<examples_canvas_baseline::Instance::OnDrawn>& event) override {
::examples_canvas_baseline::Point top_left = event.top_left();
::examples_canvas_baseline::Point bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_baseline::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_baseline::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_baseline::Point(x, y);
}
using Line = ::std::array<::examples_canvas_baseline::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
Line line = ParseLine(action);
fit::result<fidl::Error> result = client->AddLine(line);
if (!result.is_ok()) {
// Check that our one-way call was enqueued successfully, and handle the error appropriately.
// In the case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: " << result.error_value();
return -1;
}
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.baseline/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_baseline::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_baseline::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_baseline::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLine(AddLineRequest& request, AddLineCompleter::Sync& completer) override {
auto points = request.line();
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request.line()) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_baseline::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_baseline::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |examples.canvas.baseline.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_baseline::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_baseline::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++ (Wire)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.baseline/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/baseline/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::WireAsyncEventHandler<examples_canvas_baseline::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::WireEvent<examples_canvas_baseline::Instance::OnDrawn>* event) override {
::examples_canvas_baseline::wire::Point top_left = event->top_left;
::examples_canvas_baseline::wire::Point bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_baseline::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_baseline::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_baseline::wire::Point{.x = x, .y = y};
}
using Line = ::fidl::Array<::examples_canvas_baseline::wire::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
Line line = ParseLine(action);
fidl::Status status = client->AddLine(line);
if (!status.ok()) {
// Check that our one-way call was enqueued successfully, and handle the error appropriately.
// In the case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: " << status.status_string();
return -1;
}
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.baseline/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_baseline::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_baseline::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_baseline::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLine(AddLineRequestView request, AddLineCompleter::Sync& completer) override {
auto points = request->line;
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request->line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_baseline::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
weak->state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_baseline::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to |examples.canvas.baseline.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_baseline::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_baseline::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/baseline/cpp/fidl.h>
#include <examples/fidl/new/canvas/baseline/hlcpp/client/config.h>
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::baseline::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::baseline::Point{.x = x, .y = y};
}
using Line = ::std::array<::examples::canvas::baseline::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::baseline::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn = [&loop](::examples::canvas::baseline::Point top_left,
::examples::canvas::baseline::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
Line line = ParseLine(action);
instance_proxy->AddLine(line);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/baseline/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples::canvas::baseline::BoundingBox bounding_box;
};
using Line = ::std::array<::examples::canvas::baseline::Point, 2>;
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::baseline::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::baseline::Instance> request)
: binding_(fidl::Binding<examples::canvas::baseline::Instance>(this)), weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(Line line) override {
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::baseline::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached to
// the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to |examples.canvas.baseline.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::baseline::Instance>(
[dispatcher](fidl::InterfaceRequest<examples::canvas::baseline::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
Improving the design
Each of the following sections explores one potential way that we could iterate on the original design. Rather than building on one another sequentially, each presents an independent way in which the base case presented above may be modified or improved.
Basic metering on client requests
Sending unmetered one way calls back and forth produces a simple design, but there are potential pitfalls: what if the server is much slower at processing updates than the client sends them? For example, the client may load a drawing consisting of many thousands of lines from some text file, and try to send them all sequentially. How can we apply back pressure to the client to prevent the server from being overwhelmed by this wave of updates?
By using the acknowledgement pattern and making the one way call AddLine(...);
into a two way AddLine(...) -> ();, we can provide feedback to the client.
This will allow the client to throttle its output as appropriate. In this
example, we'll simply have the client wait for the ack before sending the next
message it has waiting, though more complex designs could send messages
optimistically, and only throttle when they receive async acks less frequently
than expected.
First, we need to define our interface definitions and test harness. The FIDL, CML, and realm interface definitions set up a scaffold that arbitrary implementations can use:
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.addlinemetered;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add a line to the canvas.
///
/// This method can be considered an improvement over the one-way case from a flow control
/// perspective, as it is now much more difficult for a well-behaved client to "get ahead" of
/// the server and overwhelm. This is because the client now waits for each request to be acked
/// by the server before proceeding. This change represents a trade-off: we get much greater
/// synchronization of message flow between the client and the server, at the cost of worse
/// performance at the limit due to the extra wait imposed by each ack.
flexible AddLine(struct {
line Line;
}) -> ();
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
CML
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.addlinemetered.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", or the string "WAIT". The former
// calls `AddLine(...)`, while the latter pauses execution until the next `->OnDrawn(...)`
// event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; WaitEnum}`
// here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.addlinemetered.Instance" },
],
expose: [
{
protocol: "examples.canvas.addlinemetered.Instance",
from: "self",
},
],
}
Realm
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.addlinemetered.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
Client and server implementations can then be written in any supported language:
Rust
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_addlinemetered::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
for action in config.script.into_iter() {
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
continue;
}
// If the action is not a "WAIT", we need to draw a line instead. Parse the string input,
// making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let line = [from, to];
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
println!("AddLine request sent: {:?}", line);
// By awaiting on the reply, we prevent the client from sending another request before the
// server is ready to handle, thereby syncing the flow rate between the two parties over
// this method.
instance.add_line(&line).await.context("Error sending request")?;
println!("AddLine response received");
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_addlinemetered::{
BoundingBox, InstanceRequest, InstanceRequestStream, Point,
},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
bounding_box: BoundingBox,
}
impl CanvasState {
/// Handler for the `AddLine` method.
fn add_line(&mut self, line: [Point; 2]) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut self.bounding_box;
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
self.changed = true
}
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change tracker.
state.changed = false
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLine { line, responder } => {
println!("AddLine request received: {:?}", line);
state_ref.lock().unwrap().add_line(line);
// Because this is now a two-way method, we must use the generated `responder`
// to send an in this case empty reply back to the client. This is the mechanic
// which syncs the flow rate between the client and server on this method,
// thereby preventing the client from "flooding" the server with unacknowledged
// work.
responder.send().context("Error responding")?;
println!("AddLine response sent");
} //
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This await does not complete, and thus the function does not return, unless the server errors
// out. The stream will await indefinitely, thereby creating a long-lived server. Here, we first
// wait for the updater task to realize the connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (Natural)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/add_line_metered/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_addlinemetered::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::Event<examples_canvas_addlinemetered::Instance::OnDrawn>& event) override {
auto top_left = event.top_left();
auto bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_addlinemetered::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_addlinemetered::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_addlinemetered::Point(x, y);
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::std::array<::examples_canvas_addlinemetered::Point, 2> ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_addlinemetered::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
client->AddLine(line).ThenExactlyOnce(
[&](fidl::Result<examples_canvas_addlinemetered::Instance::AddLine>& result) {
// Check if the FIDL call succeeded or not.
if (!result.is_ok()) {
// Check that our two-way call succeeded, and handle the error appropriately. In the
// case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: "
<< result.error_value().FormatDescription();
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_addlinemetered::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_addlinemetered::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](InstanceImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(AddLineRequest& request, AddLineCompleter::Sync& completer) override {
auto points = request.line();
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request.line()) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |completer| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
completer.Reply();
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_addlinemetered::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::ServerBindingRef<examples_canvas_addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_addlinemetered::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++ (Wire)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/add_line_metered/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::WireAsyncEventHandler<examples_canvas_addlinemetered::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(fidl::WireEvent<examples_canvas_addlinemetered::Instance::OnDrawn>* event) override {
auto top_left = event->top_left;
auto bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_addlinemetered::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_addlinemetered::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_addlinemetered::wire::Point{.x = x, .y = y};
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::fidl::Array<::examples_canvas_addlinemetered::wire::Point, 2> ParseLine(
const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_addlinemetered::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
client->AddLine(line).ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_canvas_addlinemetered::Instance::AddLine>& result) {
// Check if the FIDL call succeeded or not.
if (!result.ok()) {
// Check that our two-way call succeeded, and handle the error appropriately. In the
// case of this example, there is nothing we can do to recover here, except to log an
// error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLine request: " << result.status_string();
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.addlinemetered/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples_canvas_addlinemetered::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_addlinemetered::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end)
: binding_(fidl::BindServer(
dispatcher, std::move(server_end), this,
[this](InstanceImpl* impl, fidl::UnbindInfo info,
fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
})),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(AddLineRequestView request, AddLineCompleter::Sync& completer) override {
auto points = request->line;
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : request->line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |completer| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
completer.Reply();
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_addlinemetered::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
weak->state_.changed = false;
},
after);
}
fidl::ServerBindingRef<examples_canvas_addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_addlinemetered::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_addlinemetered::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/addlinemetered/cpp/fidl.h>
#include <examples/fidl/new/canvas/add_line_metered/hlcpp/client/config.h>
#include "lib/fpromise/result.h"
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::addlinemetered::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::addlinemetered::Point{.x = x, .y = y};
}
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
::std::array<::examples::canvas::addlinemetered::Point, 2> ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::addlinemetered::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn = [&loop](
::examples::canvas::addlinemetered::Point top_left,
::examples::canvas::addlinemetered::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
for (const auto& action : conf.script()) {
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
continue;
}
// Draw a line to the canvas by calling the server, using the two points we just parsed
// above as arguments.
auto line = ParseLine(action);
FX_LOGS(INFO) << "AddLine request sent: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
instance_proxy->AddLine(line, [&](fpromise::result<void, fidl::FrameworkErr> result) {
if (result.is_error()) {
// Check that our flexible two-way call was known to the server and handle the case of an
// unknown method appropriately. In the case of this example, there is nothing we can do to
// recover here, except to log an error and exit the program.
FX_LOGS(ERROR) << "Server does not implement AddLine";
}
FX_LOGS(INFO) << "AddLine response received";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/addlinemetered/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
examples::canvas::addlinemetered::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::addlinemetered::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::addlinemetered::Instance> request)
: binding_(fidl::Binding<examples::canvas::addlinemetered::Instance>(this)),
weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLine(::std::array<::examples::canvas::addlinemetered::Point, 2> line,
AddLineCallback callback) override {
FX_LOGS(INFO) << "AddLine request received: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : line) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
// Because this is now a two-way method, we must use the generated |callback| to send an in
// this case empty reply back to the client. This is the mechanic which syncs the flow rate
// between the client and server on this method, thereby preventing the client from "flooding"
// the server with unacknowledged work.
callback(fpromise::ok());
FX_LOGS(INFO) << "AddLine response sent";
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one.
if (!weak->state_.changed) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change tracker.
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::addlinemetered::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached to
// the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to
// |examples.canvas.addlinemetered.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::addlinemetered::Instance>(
[dispatcher](fidl::InterfaceRequest<examples::canvas::addlinemetered::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
Clients explicitly request draw operations
One way to improve the performance of the Instance protocol is to allow the
batching of lines: rather than sending a single AddLine(...); every time we
have a new line we'd like to add to the canvas, waiting for the reply, then
doing it again for the next line, we can instead batch many lines into a single
invocation of the new AddLines(...); call. The client can now decide how to
best segment a large collection of lines to be drawn.
Naively implemented, we would find ourselves in a situation where the server and
the client are completely unsynchronized: the client can flood the server with
unbounded AddLines(...); calls, and the server can similarly flood the client
with more -> OnDrawn(...); events than it can handle. The solution to both of
these problems is to add a simple Ready() -> (); method for synchronization
purposes. This method is called by the client whenever it is prepared to receive
the next draw update, with the response from the server indicating that the client
can proceed with more requests.
We now have some flow control in both directions. The protocol now implements
the feed forward pattern, allowing many uncontrolled calls before some
synchronizing "commit" call triggers the actual work on the server. This
prevents the client from overwhelming the server with work. Similarly, the
server is no longer allowed to send unbounded -> OnDrawn(...); events: each
event must follow a signal from the client, the Ready() -> (); call, that
indicates that it is ready to do more work. This is known as the throttled
event pattern.
The concrete implementations must apply some of these rules manually: the client
must close the connection if it receives an -> OnDrawn(...); event it did not
request via the Ready() -> (); method.
The FIDL, CML, and realm interface definitions are as follows:
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.canvas.clientrequesteddraw;
/// A point in 2D space.
type Point = struct {
x int64;
y int64;
};
/// A line in 2D space.
alias Line = array<Point, 2>;
/// A bounding box in 2D space. This is the result of "drawing" operations on our canvas, and what
/// the server reports back to the client. These bounds are sufficient to contain all of the
/// lines (inclusive) on a canvas at a given time.
type BoundingBox = struct {
top_left Point;
bottom_right Point;
};
/// Manages a single instance of a canvas. Each session of this protocol is responsible for a new
/// canvas.
@discoverable
open protocol Instance {
/// Add multiple lines to the canvas. We are able to reduce protocol chatter and the number of
/// requests needed by batching instead of calling the simpler `AddLine(...)` one line at a
/// time.
flexible AddLines(struct {
lines vector<Line>;
});
/// Rather than the server randomly performing draws, or trying to guess when to do so, the
/// client must explicitly ask for them. This creates a bit of extra chatter with the additional
/// method invocation, but allows much greater client-side control of when the canvas is "ready"
/// for a view update, thereby eliminating unnecessary draws.
///
/// This method also has the benefit of "throttling" the `-> OnDrawn(...)` event - rather than
/// allowing a potentially unlimited flood of `-> OnDrawn(...)` calls, we now have the runtime
/// enforced semantic that each `-> OnDrawn(...)` call must follow a unique `Ready() -> ()` call
/// from the client. An unprompted `-> OnDrawn(...)` is invalid, and should cause the channel to
/// immediately close.
flexible Ready() -> ();
/// Update the client with the latest drawing state. The server makes no guarantees about how
/// often this event occurs - it could occur multiple times per board state, for example.
flexible -> OnDrawn(BoundingBox);
};
CML
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
config: {
// A script for the client to follow. Entries in the script may take one of two forms: a
// pair of signed-integer coordinates like "-2,15:4,5", or the string "READY". The former
// builds a local vector sent via a single `AddLines(...)` call, while the latter sends a
// `Ready() -> ()` call pauses execution until the next `->OnDrawn(...)` event is received.
//
// TODO(https://fxbug.dev/42178362): It would absolve individual language implementations of a great
// deal of string parsing if we were able to use a vector of `union { Point; Ready}` here.
script: {
type: "vector",
max_count: 100,
element: {
type: "string",
max_size: 64,
},
},
},
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.canvas.clientrequesteddraw.Instance" },
],
expose: [
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "self",
},
],
}
Realm
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.canvas.clientrequesteddraw.Instance",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
Client and server implementations can then be written in any supported language:
Rust
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{format_err, Context as _, Error},
config::Config,
fidl_examples_canvas_clientrequesteddraw::{InstanceEvent, InstanceMarker, Point},
fuchsia_component::client::connect_to_protocol,
futures::TryStreamExt,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send Instance requests
// across the channel.
let instance = connect_to_protocol::<InstanceMarker>()?;
println!("Outgoing connection enabled");
let mut batched_lines = Vec::<[Point; 2]>::new();
for action in config.script.into_iter() {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if action == "PUSH" {
instance.add_lines(&batched_lines).context("Could not send lines")?;
println!("AddLines request sent");
batched_lines.clear();
continue;
}
// If the next action in the script is to "WAIT", block until an OnDrawn event is received
// from the server.
if action == "WAIT" {
let mut event_stream = instance.take_event_stream();
loop {
match event_stream
.try_next()
.await
.context("Error getting event response from proxy")?
.ok_or_else(|| format_err!("Proxy sent no events"))?
{
InstanceEvent::OnDrawn { top_left, bottom_right } => {
println!(
"OnDrawn event received: top_left: {:?}, bottom_right: {:?}",
top_left, bottom_right
);
break;
}
InstanceEvent::_UnknownEvent { ordinal, .. } => {
println!("Received an unknown event with ordinal {ordinal}");
}
}
}
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
println!("Ready request sent");
instance.ready().await.context("Could not send ready call")?;
println!("Ready success");
continue;
}
// Add a line to the next batch. Parse the string input, making two points out of it.
let mut points = action
.split(":")
.map(|point| {
let integers = point
.split(",")
.map(|integer| integer.parse::<i64>().unwrap())
.collect::<Vec<i64>>();
Point { x: integers[0], y: integers[1] }
})
.collect::<Vec<Point>>();
// Assemble a line from the two points.
let from = points.pop().ok_or(format_err!("line requires 2 points, but has 0"))?;
let to = points.pop().ok_or(format_err!("line requires 2 points, but has 1"))?;
let mut line: [Point; 2] = [from, to];
// Batch a line for drawing to the canvas using the two points provided.
println!("AddLines batching line: {:?}", &mut line);
batched_lines.push(line);
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{anyhow, Context as _, Error},
fidl::endpoints::RequestStream as _,
fidl_examples_canvas_clientrequesteddraw::{
BoundingBox, InstanceRequest, InstanceRequestStream, Point,
},
fuchsia_async::{Time, Timer},
fuchsia_component::server::ServiceFs,
fuchsia_zircon::{self as zx},
futures::future::join,
futures::prelude::*,
std::sync::{Arc, Mutex},
};
// A struct that stores the two things we care about for this example: the bounding box the lines
// that have been added thus far, and bit to track whether or not there have been changes since the
// last `OnDrawn` event.
#[derive(Debug)]
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
changed: bool,
// Tracks whether or not the client has declared itself ready to receive more updated.
ready: bool,
bounding_box: BoundingBox,
}
/// Handler for the `AddLines` method.
fn add_lines(state: &mut CanvasState, lines: Vec<[Point; 2]>) {
// Update the bounding box to account for the new lines we've just "added" to the canvas.
let bounds = &mut state.bounding_box;
for line in lines {
println!("AddLines printing line: {:?}", line);
for point in line {
if point.x < bounds.top_left.x {
bounds.top_left.x = point.x;
}
if point.y > bounds.top_left.y {
bounds.top_left.y = point.y;
}
if point.x > bounds.bottom_right.x {
bounds.bottom_right.x = point.x;
}
if point.y < bounds.bottom_right.y {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next tick.
state.changed = true
}
/// Creates a new instance of the server, paired to a single client across a zircon channel.
async fn run_server(stream: InstanceRequestStream) -> Result<(), Error> {
// Create a new in-memory state store for the state of the canvas. The store will live for the
// lifetime of the connection between the server and this particular client.
let state = Arc::new(Mutex::new(CanvasState {
changed: true,
ready: true,
bounding_box: BoundingBox {
top_left: Point { x: 0, y: 0 },
bottom_right: Point { x: 0, y: 0 },
},
}));
// Take ownership of the control_handle from the stream, which will allow us to push events from
// a different async task.
let control_handle = stream.control_handle();
// A separate watcher task periodically "draws" the canvas, and notifies the client of the new
// state. We'll need a cloned reference to the canvas state to be accessible from the new
// task.
let state_ref = state.clone();
let update_sender = || async move {
loop {
// Our server sends one update per second, but only if the client has declared that it
// is ready to receive one.
Timer::new(Time::after(zx::Duration::from_seconds(1))).await;
let mut state = state_ref.lock().unwrap();
if !state.changed || !state.ready {
continue;
}
// After acquiring the lock, this is where we would draw the actual lines. Since this is
// just an example, we'll avoid doing the actual rendering, and simply send the bounding
// box to the client instead.
let bounds = state.bounding_box;
match control_handle.send_on_drawn(&bounds.top_left, &bounds.bottom_right) {
Ok(_) => println!(
"OnDrawn event sent: top_left: {:?}, bottom_right: {:?}",
bounds.top_left, bounds.bottom_right
),
Err(_) => return,
}
// Reset the change and ready trackers.
state.ready = false;
state.changed = false;
}
};
// Handle requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
let state_ref = &state;
let request_handler =
stream.map(|result| result.context("failed request")).try_for_each(|request| async move {
// Match based on the method being invoked.
match request {
InstanceRequest::AddLines { lines, .. } => {
println!("AddLines request received");
add_lines(&mut state_ref.lock().unwrap(), lines);
}
InstanceRequest::Ready { responder, .. } => {
println!("Ready request received");
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();`
// event; if two "consecutive" `Ready() -> ();` calls are received, this
// interaction has entered an invalid state, and should be aborted immediately.
let mut state = state_ref.lock().unwrap();
if state.ready == true {
return Err(anyhow!("Invalid back-to-back `Ready` requests received"));
}
state.ready = true;
responder.send().context("Error responding")?;
} //
InstanceRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
});
// This line will only be reached if the server errors out. The stream will await indefinitely,
// thereby creating a long-lived server. Here, we first wait for the updater task to realize the
// connection has died, then bubble up the error.
join(request_handler, update_sender()).await.0
}
// A helper enum that allows us to treat a `Instance` service instance as a value.
enum IncomingService {
Instance(InstanceRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Instance` protocol - this will allow the client to see
// the server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Instance);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Instance(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (Natural)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_natural/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler : public fidl::AsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::Event<examples_canvas_clientrequesteddraw::Instance::OnDrawn>& event) override {
::examples_canvas_clientrequesteddraw::Point top_left = event.top_left();
::examples_canvas_clientrequesteddraw::Point bottom_right = event.bottom_right();
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y() << " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::Point(x, y);
}
using Line = ::std::array<::examples_canvas_clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fit::result<fidl::Error> result = client->AddLines(batched_lines);
if (!result.is_ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << result.error_value();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::Result<examples_canvas_clientrequesteddraw::Instance::Ready> result) {
// Check if the FIDL call succeeded or not.
if (result.is_ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error_value();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x() << ", y: " << line[1].y()
<< " }, Point { x: " << line[0].x() << ", y: " << line[0].y() << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequest& request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request.lines()) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x()
<< ", y: " << points[1].y() << " }, Point { x: " << points[0].x()
<< ", y: " << points[0].y() << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x() < bounds.top_left().x()) {
bounds.top_left().x() = point.x();
}
if (point.y() > bounds.top_left().y()) {
bounds.top_left().y() = point.y();
}
if (point.x() > bounds.bottom_right().x()) {
bounds.bottom_right().x() = point.x();
}
if (point.y() < bounds.bottom_right().y()) {
bounds.bottom_right().y() = point.y();
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto result = fidl::SendEvent(binding_)->OnDrawn(state_.bounding_box);
if (!result.is_ok()) {
return;
}
auto top_left = state_.bounding_box.top_left();
auto bottom_right = state_.bounding_box.bottom_right();
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x()
<< ", y: " << top_left.y()
<< " }, bottom_right: Point { x: " << bottom_right.x()
<< ", y: " << bottom_right.y() << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
C++ (Wire)
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/component/incoming/cpp/protocol.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/fidl/new/canvas/client_requested_draw/cpp_wire/client/config.h>
// The |EventHandler| is a derived class that we pass into the |fidl::WireClient| to handle incoming
// events asynchronously.
class EventHandler
: public fidl::WireAsyncEventHandler<examples_canvas_clientrequesteddraw::Instance> {
public:
// Handler for |OnDrawn| events sent from the server.
void OnDrawn(
fidl::WireEvent<examples_canvas_clientrequesteddraw::Instance::OnDrawn>* event) override {
::examples_canvas_clientrequesteddraw::wire::Point top_left = event->top_left;
::examples_canvas_clientrequesteddraw::wire::Point bottom_right = event->bottom_right;
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop_.Quit();
}
void on_fidl_error(fidl::UnbindInfo error) override { FX_LOGS(ERROR) << error; }
void handle_unknown_event(
fidl::UnknownEventMetadata<examples_canvas_clientrequesteddraw::Instance> metadata) override {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << metadata.event_ordinal;
}
explicit EventHandler(async::Loop& loop) : loop_(loop) {}
private:
async::Loop& loop_;
};
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples_canvas_clientrequesteddraw::wire::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples_canvas_clientrequesteddraw::wire::Point{.x = x, .y = y};
}
using Line = ::fidl::Array<::examples_canvas_clientrequesteddraw::wire::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop and dispatcher.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
// |zx::result| and it must be checked for errors.
zx::result client_end = component::Connect<examples_canvas_clientrequesteddraw::Instance>();
if (!client_end.is_ok()) {
FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
<< client_end.status_string();
return -1;
}
// Create an instance of the event handler.
EventHandler event_handler(loop);
// Create an asynchronous client using the newly-established connection.
fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
FX_LOGS(INFO) << "Outgoing connection enabled";
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
fidl::Status status = client->AddLines(fidl::VectorView<Line>::FromExternal(batched_lines));
if (!status.ok()) {
// Check that our one-way call was enqueued successfully, and handle the error
// appropriately. In the case of this example, there is nothing we can do to recover here,
// except to log an error and exit the program.
FX_LOGS(ERROR) << "Could not send AddLines request: " << status.error();
return -1;
}
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are
// ready for us.
FX_LOGS(INFO) << "Ready request sent";
client->Ready().ThenExactlyOnce(
[&](fidl::WireUnownedResult<examples_canvas_clientrequesteddraw::Instance::Ready>&
result) {
// Check if the FIDL call succeeded or not.
if (result.ok()) {
FX_LOGS(INFO) << "Ready success";
} else {
FX_LOGS(ERROR) << "Could not send Ready request: " << result.error();
}
// Quit the loop, thereby handing control back to the outer loop of actions being
// iterated over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <fidl/examples.canvas.clientrequesteddraw/cpp/wire.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async/cpp/task.h>
#include <lib/component/outgoing/cpp/outgoing_directory.h>
#include <lib/fidl/cpp/wire/channel.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples_canvas_clientrequesteddraw::wire::BoundingBox bounding_box;
};
// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_clientrequesteddraw::Instance> {
public:
// Bind this implementation to a channel.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end)
: binding_(dispatcher, std::move(server_end), this, std::mem_fn(&InstanceImpl::OnFidlClosed)),
weak_factory_(this) {
// Start the update timer on startup. Our server sends one update per second
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void OnFidlClosed(fidl::UnbindInfo info) {
if (info.reason() != ::fidl::Reason::kPeerClosedWhileReading) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
}
void AddLines(AddLinesRequestView request, AddLinesCompleter::Sync& completer) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : request->lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next |OnDrawn|
// event.
state_.changed = true;
}
void Ready(ReadyCompleter::Sync& completer) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if two
// "consecutive" `Ready() -> ();` calls are received, this interaction has entered an invalid
// state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
completer.Reply();
}
void handle_unknown_method(
fidl::UnknownMethodMetadata<examples_canvas_clientrequesteddraw::Instance> metadata,
fidl::UnknownMethodCompleter::Sync& completer) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << metadata.method_ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something has
// changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client has
// not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = weak->state_.bounding_box.top_left;
auto bottom_right = weak->state_.bounding_box.bottom_right;
fidl::Status status =
fidl::WireSendEvent(weak->binding_)->OnDrawn(top_left, bottom_right);
if (!status.ok()) {
return;
}
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
weak->state_.changed = false;
},
after);
}
fidl::ServerBinding<examples_canvas_clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from the
// client. The following initializes the loop, and obtains the dispatcher, which will be used when
// binding the server implementation to a channel.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component. This
// directory is where the outgoing FIDL protocols are installed so that they can be provided to
// other components.
component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
// The `ServeFromStartupInfo()` function sets up the outgoing directory with the startup handle.
// The startup handle is a handle provided to every component by the system, so that they can
// serve capabilities (e.g. FIDL protocols) to other components.
zx::result result = outgoing.ServeFromStartupInfo();
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
return -1;
}
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
result = outgoing.AddUnmanagedProtocol<examples_canvas_clientrequesteddraw::Instance>(
[dispatcher](fidl::ServerEnd<examples_canvas_clientrequesteddraw::Instance> server_end) {
// Create an instance of our InstanceImpl that destroys itself when the connection closes.
new InstanceImpl(dispatcher, std::move(server_end));
});
if (result.is_error()) {
FX_LOGS(ERROR) << "Failed to add Instance protocol: " << result.status_string();
return -1;
}
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}
HLCPP
Client
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <charconv>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <examples/fidl/new/canvas/client_requested_draw/hlcpp/client/config.h>
// A helper function that takes a coordinate in string form, like "123,-456", and parses it into a
// a struct of the form |{ in64 x; int64 y; }|.
::examples::canvas::clientrequesteddraw::Point ParsePoint(std::string_view input) {
int64_t x = 0;
int64_t y = 0;
size_t index = input.find(',');
if (index != std::string::npos) {
std::from_chars(input.data(), input.data() + index, x);
std::from_chars(input.data() + index + 1, input.data() + input.length(), y);
}
return ::examples::canvas::clientrequesteddraw::Point{.x = x, .y = y};
}
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// A helper function that takes a coordinate pair in string form, like "1,2:-3,-4", and parses it
// into an array of 2 |Point| structs.
Line ParseLine(const std::string& action) {
auto input = std::string_view(action);
size_t index = input.find(':');
if (index != std::string::npos) {
return {ParsePoint(input.substr(0, index)), ParsePoint(input.substr(index + 1))};
}
return {};
}
int main(int argc, const char** argv) {
FX_LOGS(INFO) << "Started";
// Retrieve component configuration.
auto conf = config::Config::TakeFromStartupHandle();
// Start up an async loop.
async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Connect to the protocol inside the component's namespace, then create an asynchronous client
// using the newly-established connection.
examples::canvas::clientrequesteddraw::InstancePtr instance_proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
FX_LOGS(INFO) << "Outgoing connection enabled";
instance_proxy.set_error_handler([&loop](zx_status_t status) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
loop.Quit();
});
// Provide a lambda to handle incoming |OnDrawn| events asynchronously.
instance_proxy.events().OnDrawn =
[&loop](::examples::canvas::clientrequesteddraw::Point top_left,
::examples::canvas::clientrequesteddraw::Point bottom_right) {
FX_LOGS(INFO) << "OnDrawn event received: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y << " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
loop.Quit();
};
instance_proxy.events().handle_unknown_event = [](uint64_t ordinal) {
FX_LOGS(WARNING) << "Received an unknown event with ordinal " << ordinal;
};
std::vector<Line> batched_lines;
for (const auto& action : conf.script()) {
// If the next action in the script is to "PUSH", send a batch of lines to the server.
if (action == "PUSH") {
instance_proxy->AddLines(batched_lines);
batched_lines.clear();
FX_LOGS(INFO) << "AddLines request sent";
continue;
}
// If the next action in the script is to "WAIT", block until an |OnDrawn| event is received
// from the server.
if (action == "WAIT") {
loop.Run();
loop.ResetQuit();
// Now, inform the server that we are ready to receive more updates whenever they are ready
// for us.
FX_LOGS(INFO) << "Ready request sent";
instance_proxy->Ready([&](fpromise::result<void, fidl::FrameworkErr> result) {
if (result.is_error()) {
// Check that our flexible two-way call was known to the server and handle the case of an
// unknown method appropriately. In the case of this example, there is nothing we can do
// to recover here, except to log an error and exit the program.
FX_LOGS(ERROR) << "Server does not implement AddLine";
}
FX_LOGS(INFO) << "Ready success";
// Quit the loop, thereby handing control back to the outer loop of actions being iterated
// over.
loop.Quit();
});
// Run the loop until the callback is resolved, at which point we can continue from here.
loop.Run();
loop.ResetQuit();
continue;
}
// Batch a line for drawing to the canvas using the two points provided.
Line line = ParseLine(action);
batched_lines.push_back(line);
FX_LOGS(INFO) << "AddLines batching line: [Point { x: " << line[1].x << ", y: " << line[1].y
<< " }, Point { x: " << line[0].x << ", y: " << line[0].y << " }]";
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
sleep(2);
return 0;
}
Server
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/async/cpp/task.h>
#include <lib/fidl/cpp/binding.h>
#include <lib/sys/cpp/component_context.h>
#include <lib/syslog/cpp/macros.h>
#include <unistd.h>
#include <examples/canvas/clientrequesteddraw/cpp/fidl.h>
#include <src/lib/fxl/macros.h>
#include <src/lib/fxl/memory/weak_ptr.h>
// A struct that stores the two things we care about for this example: the set of lines, and the
// bounding box that contains them.
struct CanvasState {
// Tracks whether there has been a change since the last send, to prevent redundant updates.
bool changed = true;
// Tracks whether or not the client has declared itself ready to receive more updated.
bool ready = true;
examples::canvas::clientrequesteddraw::BoundingBox bounding_box;
};
using Line = ::std::array<::examples::canvas::clientrequesteddraw::Point, 2>;
// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::clientrequesteddraw::Instance {
public:
// Bind this implementation to an |InterfaceRequest|.
InstanceImpl(async_dispatcher_t* dispatcher,
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request)
: binding_(fidl::Binding<examples::canvas::clientrequesteddraw::Instance>(this)),
weak_factory_(this) {
binding_.Bind(std::move(request), dispatcher);
// Gracefully handle abrupt shutdowns.
binding_.set_error_handler([this](zx_status_t status) mutable {
if (status != ZX_ERR_PEER_CLOSED) {
FX_LOGS(ERROR) << "Shutdown unexpectedly";
}
delete this;
});
// Start the update timer on startup. Our server sends one update per second.
ScheduleOnDrawnEvent(dispatcher, zx::sec(1));
}
void AddLines(std::vector<Line> lines) override {
FX_LOGS(INFO) << "AddLines request received";
for (const auto& points : lines) {
FX_LOGS(INFO) << "AddLines printing line: [Point { x: " << points[1].x
<< ", y: " << points[1].y << " }, Point { x: " << points[0].x
<< ", y: " << points[0].y << " }]";
// Update the bounding box to account for the new line we've just "added" to the canvas.
auto& bounds = state_.bounding_box;
for (const auto& point : points) {
if (point.x < bounds.top_left.x) {
bounds.top_left.x = point.x;
}
if (point.y > bounds.top_left.y) {
bounds.top_left.y = point.y;
}
if (point.x > bounds.bottom_right.x) {
bounds.bottom_right.x = point.x;
}
if (point.y < bounds.bottom_right.y) {
bounds.bottom_right.y = point.y;
}
}
}
// Mark the state as "dirty", so that an update is sent back to the client on the next
// |OnDrawn| event.
state_.changed = true;
}
void Ready(ReadyCallback callback) override {
FX_LOGS(INFO) << "Ready request received";
// The client must only call `Ready() -> ();` after receiving an `-> OnDrawn();` event; if
// two "consecutive" `Ready() -> ();` calls are received, this interaction has entered an
// invalid state, and should be aborted immediately.
if (state_.ready == true) {
FX_LOGS(ERROR) << "Invalid back-to-back `Ready` requests received";
}
state_.ready = true;
callback(fpromise::ok());
}
void handle_unknown_method(uint64_t ordinal, bool method_has_response) override {
FX_LOGS(WARNING) << "Received an unknown method with ordinal " << ordinal;
}
private:
// Each scheduled update waits for the allotted amount of time, sends an update if something
// has changed, and schedules the next update.
void ScheduleOnDrawnEvent(async_dispatcher_t* dispatcher, zx::duration after) {
async::PostDelayedTask(
dispatcher,
[&, dispatcher, after, weak = weak_factory_.GetWeakPtr()] {
// Halt execution if the binding has been deallocated already.
if (!weak) {
return;
}
// Schedule the next update if the binding still exists.
weak->ScheduleOnDrawnEvent(dispatcher, after);
// No need to send an update if nothing has changed since the last one, or the client
// has not yet informed us that it is ready for more updates.
if (!weak->state_.changed || !weak->state_.ready) {
return;
}
// This is where we would draw the actual lines. Since this is just an example, we'll
// avoid doing the actual rendering, and simply send the bounding box to the client
// instead.
auto top_left = state_.bounding_box.top_left;
auto bottom_right = state_.bounding_box.bottom_right;
binding_.events().OnDrawn(top_left, bottom_right);
FX_LOGS(INFO) << "OnDrawn event sent: top_left: Point { x: " << top_left.x
<< ", y: " << top_left.y
<< " }, bottom_right: Point { x: " << bottom_right.x
<< ", y: " << bottom_right.y << " }";
// Reset the change and ready trackers.
state_.ready = false;
state_.changed = false;
},
after);
}
fidl::Binding<examples::canvas::clientrequesteddraw::Instance> binding_;
CanvasState state_ = CanvasState{};
// Generates weak references to this object, which are appropriate to pass into asynchronous
// callbacks that need to access this object. The references are automatically invalidated
// if this object is destroyed.
fxl::WeakPtrFactory<InstanceImpl> weak_factory_;
};
int main(int argc, char** argv) {
FX_LOGS(INFO) << "Started";
// The event loop is used to asynchronously listen for incoming connections and requests from
// the client. The following initializes the loop, and obtains the dispatcher, which will be
// used when binding the server implementation to a channel.
//
// Note that unlike the new C++ bindings, HLCPP bindings rely on the async loop being attached
// to the current thread via the |kAsyncLoopConfigAttachToCurrentThread| configuration.
async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
async_dispatcher_t* dispatcher = loop.dispatcher();
// Create an |OutgoingDirectory| instance.
//
// The |component::OutgoingDirectory| class serves the outgoing directory for our component.
// This directory is where the outgoing FIDL protocols are installed so that they can be
// provided to other components.
auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
// Register a handler for components trying to connect to
// |examples.canvas.clientrequesteddraw.Instance|.
context->outgoing()->AddPublicService(
fidl::InterfaceRequestHandler<examples::canvas::clientrequesteddraw::Instance>(
[dispatcher](
fidl::InterfaceRequest<examples::canvas::clientrequesteddraw::Instance> request) {
// Create an instance of our |InstanceImpl| that destroys itself when the connection
// closes.
new InstanceImpl(dispatcher, std::move(request));
}));
// Everything is wired up. Sit back and run the loop until an incoming connection wakes us up.
FX_LOGS(INFO) << "Listening for incoming connections";
loop.Run();
return 0;
}