wayland_bridge/
object.rs

1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5///! This module provides types for managing the set of wayland objects for a
6///! connection. The |ObjectMap| associates a numeric object id with a
7///! |MessageReceiver| that can interpret the message and provide the logic to
8///! implement the interface contract for that object.
9///!
10///! At a high level, the |RequestReceiver<I:Interface>| trait allows for a
11///! decoded request to be interacted with. In the middle we provide the
12///! |RequestDispatcher| struct that implements the |MessageReceiver| trait
13///! by decoding the |Message| into the concrete |Request| type for the
14///! |Interface|.
15///!
16///! Consumers should mostly have to only concern themselves with the
17///! |RequestReceiver<I:Interface>| trait, with the other types being mostly the
18///! glue and dispatch logic.
19use {
20    crate::client::Client,
21    anyhow::{format_err, Error},
22    fuchsia_trace as ftrace,
23    fuchsia_wayland_core::{self as wl, FromArgs, MessageType},
24    std::{
25        any::Any,
26        collections::{
27            hash_map::{Entry, HashMap},
28            HashSet,
29        },
30        fmt::{self, Debug},
31        marker::PhantomData,
32    },
33    thiserror::Error,
34};
35
36/// The |ObjectMap| holds the state of active objects for a single connection.
37///
38/// When a new connection is established, the server should populate the
39/// |ObjectMap| with the "wl_display" singleton object. From the client can
40/// query the registry and bind new objects to the interfaces the client
41/// understands.
42pub(crate) struct ObjectMap {
43    /// The set of active objects. This holds the descriptors of supported
44    /// messages for each object, as well as the |MessageReceiver| that's
45    /// capable of handling the requests.
46    objects: HashMap<u32, ObjectMapEntry>,
47}
48
49struct ObjectMapEntry {
50    /// The opcodes and method signatures accepted by this object.
51    request_spec: &'static wl::MessageGroupSpec,
52    /// The handler for this object.
53    receiver: Box<dyn MessageReceiver>,
54}
55
56#[derive(Copy, Clone, Debug, Error)]
57pub enum ObjectMapError {
58    /// An error raised if a message is received with the 'sender' field set
59    /// to an unknown object (ex: either the object has not been created yet
60    /// or it has already been deleted).
61    #[error("Object with id {} is not found", _0)]
62    InvalidObjectId(u32),
63
64    /// An error raised if a message is delivered to an object with an
65    /// unsupported or unknown opcode.
66    #[error("Opcode {} is not supported", _0)]
67    InvalidOpcode(u16),
68}
69
70/// Errors generated when looking up objects from the map.
71#[derive(Debug, Error)]
72pub enum ObjectLookupError {
73    #[error("Object with id {} does not exist", _0)]
74    ObjectDoesNotExist(u32),
75    #[error("Failed to downcast")]
76    DowncastFailed,
77}
78
79impl ObjectMap {
80    pub fn new() -> Self {
81        ObjectMap { objects: HashMap::new() }
82    }
83
84    /// Looks up an object in the map and returns a downcasted reference to
85    /// the implementation.
86    pub fn get<T: Any>(&self, id: wl::ObjectId) -> Result<&T, ObjectLookupError> {
87        ftrace::duration!(c"wayland", c"ObjectMap::get");
88        match self.objects.get(&id) {
89            Some(entry) => match entry.receiver.data().downcast_ref() {
90                Some(t) => Ok(t),
91                None => Err(ObjectLookupError::DowncastFailed),
92            },
93            None => Err(ObjectLookupError::ObjectDoesNotExist(id)),
94        }
95    }
96
97    /// Looks up an object in the map and returns a downcasted mutable
98    /// reference to the implementation.
99    pub fn get_mut<T: Any>(&mut self, id: wl::ObjectId) -> Result<&mut T, ObjectLookupError> {
100        ftrace::duration!(c"wayland", c"ObjectMap::get_mut");
101        match self.objects.get_mut(&id) {
102            Some(entry) => match entry.receiver.data_mut().downcast_mut() {
103                Some(t) => Ok(t),
104                None => Err(ObjectLookupError::DowncastFailed),
105            },
106            None => Err(ObjectLookupError::ObjectDoesNotExist(id)),
107        }
108    }
109
110    /// Looks up the receiver function and the message structure from the map.
111    pub(crate) fn lookup_internal(
112        &self,
113        header: &wl::MessageHeader,
114    ) -> Result<(MessageReceiverFn, &'static wl::MessageSpec), Error> {
115        ftrace::duration!(c"wayland", c"ObjectMap::lookup_internal");
116        let ObjectMapEntry { request_spec, receiver } = self
117            .objects
118            .get(&header.sender)
119            .ok_or(ObjectMapError::InvalidObjectId(header.sender))?;
120        let spec = request_spec
121            .0
122            .get(header.opcode as usize)
123            .ok_or(ObjectMapError::InvalidOpcode(header.opcode))?;
124
125        Ok((receiver.receiver(), spec))
126    }
127
128    /// Adds a new object into the map that will handle messages with the sender
129    /// set to |id|. When a message is received with the corresponding |id|, the
130    /// message will be decoded and forwarded to the |RequestReceiver|.
131    ///
132    /// Returns Err if there is already an object for |id| in this |ObjectMap|.
133    pub fn add_object<I: wl::Interface + 'static, R: RequestReceiver<I> + 'static>(
134        &mut self,
135        id: u32,
136        receiver: R,
137    ) -> Result<ObjectRef<R>, Error> {
138        ftrace::duration!(c"wayland", c"ObjectMap::add_object");
139        self.add_object_raw(id, Box::new(RequestDispatcher::new(receiver)), &I::REQUESTS)?;
140        Ok(ObjectRef::from_id(id))
141    }
142
143    /// Adds an object to the map using the low-level primitives. It's favorable
144    /// to use instead |add_object| if the wayland interface for the object is
145    /// statically known.
146    pub fn add_object_raw(
147        &mut self,
148        id: wl::ObjectId,
149        receiver: Box<dyn MessageReceiver>,
150        request_spec: &'static wl::MessageGroupSpec,
151    ) -> Result<(), Error> {
152        ftrace::duration!(c"wayland", c"ObjectMap::add_object_raw");
153        if let Entry::Vacant(entry) = self.objects.entry(id) {
154            entry.insert(ObjectMapEntry { receiver, request_spec });
155            Ok(())
156        } else {
157            Err(format_err!("Can't add duplicate object with id {}. ", id))
158        }
159    }
160
161    pub fn delete(&mut self, id: wl::ObjectId) -> Result<(), Error> {
162        ftrace::duration!(c"wayland", c"ObjectMap::delete");
163        if self.objects.remove(&id).is_some() {
164            // TODO: Send wl_display::delete_id.
165            Ok(())
166        } else {
167            Err(format_err!("Item {} does not exist", id))
168        }
169    }
170}
171
172/// When the concrete type of an object is known statically, we can provide
173/// an ObjectRef wrapper around the ObjectId in order to make downcasting
174/// simpler.
175///
176/// This is primarily useful when vending self references to MessageReceviers.
177pub struct ObjectRef<T: 'static>(PhantomData<T>, wl::ObjectId);
178
179// We cannot just derive these since that will place the corresponding trait
180// bound on `T`.
181impl<T: 'static> Copy for ObjectRef<T> {}
182impl<T: 'static> Clone for ObjectRef<T> {
183    fn clone(&self) -> Self {
184        *self
185    }
186}
187impl<T: 'static> Debug for ObjectRef<T> {
188    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
189        write!(f, "ObjectRef({})", self.1)
190    }
191}
192impl<T> From<wl::ObjectId> for ObjectRef<T> {
193    fn from(id: wl::ObjectId) -> Self {
194        Self::from_id(id)
195    }
196}
197impl<T> Eq for ObjectRef<T> {}
198impl<T> PartialEq for ObjectRef<T> {
199    fn eq(&self, other: &Self) -> bool {
200        self.1.eq(&other.1)
201    }
202}
203impl<T> std::hash::Hash for ObjectRef<T> {
204    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
205        self.1.hash(state);
206    }
207}
208
209impl<T> ObjectRef<T> {
210    pub fn from_id(id: wl::ObjectId) -> Self {
211        ObjectRef(PhantomData, id)
212    }
213
214    pub fn id(&self) -> wl::ObjectId {
215        self.1
216    }
217
218    /// Provides an immutable reference to an object, downcasted to |T|.
219    pub fn get<'a>(&self, client: &'a Client) -> Result<&'a T, ObjectLookupError> {
220        client.get_object(self.1)
221    }
222
223    /// Provides an immutable reference to an object, downcasted to |T|, if available.
224    pub fn try_get<'a>(&self, client: &'a Client) -> Option<&'a T> {
225        client.try_get_object(self.1)
226    }
227
228    /// Provides a mutable reference to an object, downcasted to |T|.
229    pub fn get_mut<'a>(&self, client: &'a mut Client) -> Result<&'a mut T, ObjectLookupError> {
230        client.get_object_mut(self.1)
231    }
232
233    /// Provides a mutable reference to an object, downcasted to |T|, if available.
234    pub fn try_get_mut<'a>(&self, client: &'a mut Client) -> Option<&'a mut T> {
235        client.try_get_object_mut(self.1)
236    }
237
238    /// Returns `true` iff the underlying object is still valid.
239    ///
240    /// Here 'valid' means that the object_id exists and refers to an object
241    /// of type `T`. This method will still return `true` if the associated
242    /// object_id has been deleted and recreated with the same type `T. If this
243    /// is not desirable then the caller must track instance with some state
244    /// embedded into `T`.
245    ///
246    /// This can be useful to verify prior to sending events using the
247    /// associated object_id but the host object itself is not required.
248    pub fn is_valid(&self, client: &mut Client) -> bool {
249        self.get(client).is_ok()
250    }
251}
252
253/// A collection of `ObjectRef`s.
254pub struct ObjectRefSet<ObjectType: 'static>(HashSet<ObjectRef<ObjectType>>);
255
256impl<ObjectType> ObjectRefSet<ObjectType> {
257    pub fn new() -> Self {
258        ObjectRefSet(HashSet::new())
259    }
260
261    /// Adds `id` into the set.
262    ///
263    /// Returns `true` iff the item was inserted. If `false` is returned then an
264    /// entry with the same id already exists in the set.
265    pub fn add(&mut self, id: ObjectRef<ObjectType>) -> bool {
266        self.0.insert(id)
267    }
268
269    /// Removes`id` from the set.
270    ///
271    /// Returns `true` iff the item was removed. If `false` is returned then an
272    /// entry with a matching `id` did not exist in the set.
273    pub fn remove(&mut self, id: ObjectRef<ObjectType>) -> bool {
274        self.0.remove(&id)
275    }
276
277    pub fn iter(&self) -> impl Iterator<Item = &ObjectRef<ObjectType>> {
278        self.0.iter()
279    }
280}
281
282pub trait NewObjectExt<I: wl::Interface> {
283    fn implement<R: RequestReceiver<I>>(
284        self,
285        client: &mut Client,
286        receiver: R,
287    ) -> Result<ObjectRef<R>, Error>;
288}
289
290impl<I: wl::Interface> NewObjectExt<I> for wl::NewObject<I> {
291    fn implement<R: RequestReceiver<I>>(
292        self,
293        client: &mut Client,
294        receiver: R,
295    ) -> Result<ObjectRef<R>, Error> {
296        client.add_object(self.id(), receiver)
297    }
298}
299
300/// A |MessageReceiver| is a type that can accept in-bound messages from a
301/// client.
302///
303/// The server will dispatch |Message|s to the appropriate |MessageReceiver|
304/// by reading the sender field in the message header.
305type MessageReceiverFn = fn(
306    this: wl::ObjectId,
307    opcode: u16,
308    args: Vec<wl::Arg>,
309    client: &mut Client,
310) -> Result<(), Error>;
311pub trait MessageReceiver {
312    /// Returns a function pointer that will be called to handle requests
313    /// targeting this object.
314    fn receiver(&self) -> MessageReceiverFn;
315
316    fn data(&self) -> &dyn Any;
317
318    fn data_mut(&mut self) -> &mut dyn Any;
319}
320
321/// The |RequestReceiver| trait is what high level code will use to work with
322/// request messages for a given type.
323pub trait RequestReceiver<I: wl::Interface>: Any + Sized {
324    /// Handle a decoded message for the associated |Interface|.
325    ///
326    /// |self| is not directly provided, but instead is provided as an
327    /// |ObjectId| that can be used to get a reference to self.
328    ///
329    /// Ex:
330    ///   struct MyReceiver;
331    ///
332    ///   impl RequestReceiver<MyInterface> for MyReceiver {
333    ///       fn receive(mut this: ObjectRef<Self>,
334    ///                  request: MyInterfaceRequest,
335    ///                  client: &mut Client
336    ///       ) -> Result<(), Error> {
337    ///           let this = self.get()?;
338    ///           let this_mut = self.get_mut()?;
339    ///       }
340    ///   }
341    fn receive(
342        this: ObjectRef<Self>,
343        request: I::Incoming,
344        client: &mut Client,
345    ) -> Result<(), Error>;
346}
347
348/// Implements a |MessageReceiver| that can decode a request into the
349/// appropriate request type for an |Interface|, and then invoke an
350/// |Implementation|
351///
352/// This struct essentially is the glue that sits in between the generic
353/// |MessageReceiver| trait that is used to dispatch raw message buffers and
354/// the higher level |RequestReceiver| that operates on the decoded request
355/// enums.
356pub struct RequestDispatcher<I: wl::Interface, R: RequestReceiver<I>> {
357    _marker: PhantomData<I>,
358    receiver: R,
359}
360
361impl<I: wl::Interface, R: RequestReceiver<I>> RequestDispatcher<I, R> {
362    pub fn new(receiver: R) -> Self {
363        RequestDispatcher { receiver, _marker: PhantomData }
364    }
365}
366
367fn receive_message<I: wl::Interface, R: RequestReceiver<I>>(
368    this: wl::ObjectId,
369    opcode: u16,
370    args: Vec<wl::Arg>,
371    client: &mut Client,
372) -> Result<(), Error> {
373    ftrace::duration!(c"wayland", c"receive_message");
374    let request = {
375        ftrace::duration!(c"wayland", c"I::Request::from_args");
376        I::Incoming::from_args(opcode, args).unwrap()
377    };
378    if client.protocol_logging() {
379        println!("--r-> {}", request.log(this));
380    }
381
382    {
383        let _scope = ftrace::duration(c"wayland", request.message_name(), &[]);
384        R::receive(ObjectRef(PhantomData, this), request, client)?;
385    }
386    Ok(())
387}
388
389/// Convert the raw Message into the appropriate request type by delegating
390/// to the associated |Request| type of |Interface|, and then invoke the
391/// receiver.
392impl<I: wl::Interface, R: RequestReceiver<I>> MessageReceiver for RequestDispatcher<I, R> {
393    fn receiver(&self) -> MessageReceiverFn {
394        receive_message::<I, R>
395    }
396
397    fn data(&self) -> &dyn Any {
398        &self.receiver
399    }
400
401    fn data_mut(&mut self) -> &mut dyn Any {
402        &mut self.receiver
403    }
404}
405
406#[cfg(test)]
407mod tests {
408    use super::*;
409
410    use fuchsia_async as fasync;
411    use fuchsia_wayland_core::IntoMessage;
412
413    use crate::display::Display;
414    use crate::registry::RegistryBuilder;
415    use crate::test_protocol::*;
416
417    fn create_client() -> Result<Client, Error> {
418        let display = Display::new_no_scenic(RegistryBuilder::new().build())
419            .expect("Failed to create display");
420        let (c1, _c2) = zx::Channel::create();
421        Ok(Client::new(fasync::Channel::from_channel(c1), display))
422    }
423
424    #[test]
425    fn dispatch_message_to_request_receiver() -> Result<(), Error> {
426        let _executor = fasync::LocalExecutor::new();
427        let mut client = create_client()?;
428        client.add_object(0, TestReceiver::new())?;
429
430        // Send a sync message; verify it's received.
431        client.handle_message(TestMessage::Message1.into_message(0)?)?;
432        assert_eq!(1, client.get_object::<TestReceiver>(0)?.count());
433        Ok(())
434    }
435
436    #[test]
437    fn add_object_duplicate_id() -> Result<(), Error> {
438        let _executor = fasync::LocalExecutor::new();
439        let mut client = create_client()?;
440        assert!(client.add_object(0, TestReceiver::new()).is_ok());
441        assert!(client.add_object(0, TestReceiver::new()).is_err());
442        Ok(())
443    }
444
445    #[test]
446    fn dispatch_message_to_invalid_id() -> Result<(), Error> {
447        let _executor = fasync::LocalExecutor::new();
448        // Send a message to an empty map.
449        let mut client = create_client()?;
450
451        assert!(client.handle_message(TestMessage::Message1.into_message(0)?).is_err());
452        Ok(())
453    }
454}
wayland_bridge/object.rs

wayland_bridge/
object.rs
