From d67e461325d530a3da8befb72670f998612cd16a Mon Sep 17 00:00:00 2001 From: Mikayla Date: Wed, 17 Jan 2024 10:00:21 -0800 Subject: [PATCH 1/3] =?UTF-8?q?document=20app=20module=20in=20gpui=20?= =?UTF-8?q?=F0=9F=8E=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit co-authored-by: Nathan --- crates/gpui/src/app.rs | 65 +++++++++++++++++++++++++++- crates/gpui/src/app/async_context.rs | 31 +++++++++++-- crates/gpui/src/app/entity_map.rs | 25 +++++++++-- crates/gpui/src/app/model_context.rs | 17 ++++++++ 4 files changed, 128 insertions(+), 10 deletions(-) diff --git a/crates/gpui/src/app.rs b/crates/gpui/src/app.rs index 41519f0ae4..ab9b4d9f86 100644 --- a/crates/gpui/src/app.rs +++ b/crates/gpui/src/app.rs @@ -1,3 +1,5 @@ +#![deny(missing_docs)] + mod async_context; mod entity_map; mod model_context; @@ -43,6 +45,9 @@ use util::{ ResultExt, }; +/// The duration for which futures returned from [AppContext::on_app_context] or [ModelContext::on_app_quit] can run before the application fully quits. +pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_millis(100); + /// Temporary(?) wrapper around [`RefCell`] to help us debug any double borrows. /// Strongly consider removing after stabilization. #[doc(hidden)] @@ -187,6 +192,9 @@ type QuitHandler = Box LocalBoxFuture<'static, () type ReleaseListener = Box; type NewViewListener = Box; +/// Contains the state of the full application, and passed as a reference to a variety of callbacks. +/// Other contexts such as [ModelContext], [WindowContext], and [ViewContext] deref to this type, making it the most general context type. +/// You need a reference to an `AppContext` to access the state of a [Model]. pub struct AppContext { pub(crate) this: Weak, pub(crate) platform: Rc, @@ -312,7 +320,7 @@ impl AppContext { let futures = futures::future::join_all(futures); if self .background_executor - .block_with_timeout(Duration::from_millis(100), futures) + .block_with_timeout(SHUTDOWN_TIMEOUT, futures) .is_err() { log::error!("timed out waiting on app_will_quit"); @@ -446,6 +454,7 @@ impl AppContext { .collect() } + /// Returns a handle to the window that is currently focused at the platform level, if one exists. pub fn active_window(&self) -> Option { self.platform.active_window() } @@ -474,14 +483,17 @@ impl AppContext { self.platform.activate(ignoring_other_apps); } + /// Hide the application at the platform level. pub fn hide(&self) { self.platform.hide(); } + /// Hide other applications at the platform level. pub fn hide_other_apps(&self) { self.platform.hide_other_apps(); } + /// Unhide other applications at the platform level. pub fn unhide_other_apps(&self) { self.platform.unhide_other_apps(); } @@ -521,18 +533,25 @@ impl AppContext { self.platform.open_url(url); } + /// Returns the full pathname of the current app bundle. + /// If the app is not being run from a bundle, returns an error. pub fn app_path(&self) -> Result { self.platform.app_path() } + /// Returns the file URL of the executable with the specified name in the application bundle pub fn path_for_auxiliary_executable(&self, name: &str) -> Result { self.platform.path_for_auxiliary_executable(name) } + /// Returns the maximum duration in which a second mouse click must occur for an event to be a double-click event. pub fn double_click_interval(&self) -> Duration { self.platform.double_click_interval() } + /// Displays a platform modal for selecting paths. + /// When one or more paths are selected, they'll be relayed asynchronously via the returned oneshot channel. + /// If cancelled, a `None` will be relayed instead. pub fn prompt_for_paths( &self, options: PathPromptOptions, @@ -540,22 +559,30 @@ impl AppContext { self.platform.prompt_for_paths(options) } + /// Displays a platform modal for selecting a new path where a file can be saved. + /// The provided directory will be used to set the iniital location. + /// When a path is selected, it is relayed asynchronously via the returned oneshot channel. + /// If cancelled, a `None` will be relayed instead. pub fn prompt_for_new_path(&self, directory: &Path) -> oneshot::Receiver> { self.platform.prompt_for_new_path(directory) } + /// Reveals the specified path at the platform level, such as in Finder on macOS. pub fn reveal_path(&self, path: &Path) { self.platform.reveal_path(path) } + /// Returns whether the user has configured scrollbars to auto-hide at the platform level. pub fn should_auto_hide_scrollbars(&self) -> bool { self.platform.should_auto_hide_scrollbars() } + /// Restart the application. pub fn restart(&self) { self.platform.restart() } + /// Returns the local timezone at the platform level. pub fn local_timezone(&self) -> UtcOffset { self.platform.local_timezone() } @@ -745,7 +772,7 @@ impl AppContext { } /// Spawns the future returned by the given function on the thread pool. The closure will be invoked - /// with AsyncAppContext, which allows the application state to be accessed across await points. + /// with [AsyncAppContext], which allows the application state to be accessed across await points. pub fn spawn(&self, f: impl FnOnce(AsyncAppContext) -> Fut) -> Task where Fut: Future + 'static, @@ -896,6 +923,8 @@ impl AppContext { self.globals_by_type.insert(global_type, lease.global); } + /// Arrange for the given function to be invoked whenever a view of the specified type is created. + /// The function will be passed a mutable reference to the view along with an appropriate context. pub fn observe_new_views( &mut self, on_new: impl 'static + Fn(&mut V, &mut ViewContext), @@ -915,6 +944,8 @@ impl AppContext { subscription } + /// Observe the release of a model or view. The callback is invoked after the model or view + /// has no more strong references but before it has been dropped. pub fn observe_release( &mut self, handle: &E, @@ -935,6 +966,9 @@ impl AppContext { subscription } + /// Register a callback to be invoked when a keystroke is received by the application + /// in any window. Note that this fires after all other action and event mechansims have resolved + /// and that this API will not be invoked if the event's propogation is stopped. pub fn observe_keystrokes( &mut self, f: impl FnMut(&KeystrokeEvent, &mut WindowContext) + 'static, @@ -958,6 +992,7 @@ impl AppContext { self.pending_effects.push_back(Effect::Refresh); } + /// Clear all key bindings in the app. pub fn clear_key_bindings(&mut self) { self.keymap.lock().clear(); self.pending_effects.push_back(Effect::Refresh); @@ -992,6 +1027,7 @@ impl AppContext { self.propagate_event = true; } + /// Build an action from some arbitrary data, typically a keymap entry. pub fn build_action( &self, name: &str, @@ -1000,10 +1036,16 @@ impl AppContext { self.actions.build_action(name, data) } + /// Get a list of all action names that have been registered. + /// in the application. Note that registration only allows for + /// actions to be built dynamically, and is unrelated to binding + /// actions in the element tree. pub fn all_action_names(&self) -> &[SharedString] { self.actions.all_action_names() } + /// Register a callback to be invoked when the application is about to quit. + /// It is not possible to cancel the quit event at this point. pub fn on_app_quit( &mut self, mut on_quit: impl FnMut(&mut AppContext) -> Fut + 'static, @@ -1039,6 +1081,8 @@ impl AppContext { } } + /// Checks if the given action is bound in the current context, as defined by the app's current focus, + /// the bindings in the element tree, and any global action listeners. pub fn is_action_available(&mut self, action: &dyn Action) -> bool { if let Some(window) = self.active_window() { if let Ok(window_action_available) = @@ -1052,10 +1096,13 @@ impl AppContext { .contains_key(&action.as_any().type_id()) } + /// Set the menu bar for this application. This will replace any existing menu bar. pub fn set_menus(&mut self, menus: Vec) { self.platform.set_menus(menus, &self.keymap.lock()); } + /// Dispatch an action to the currently active window or global action handler + /// See [action::Action] for more information on how actions work pub fn dispatch_action(&mut self, action: &dyn Action) { if let Some(active_window) = self.active_window() { active_window @@ -1110,6 +1157,7 @@ impl AppContext { } } + /// Is there currently something being dragged? pub fn has_active_drag(&self) -> bool { self.active_drag.is_some() } @@ -1262,8 +1310,14 @@ impl DerefMut for GlobalLease { /// Contains state associated with an active drag operation, started by dragging an element /// within the window or by dragging into the app from the underlying platform. pub struct AnyDrag { + /// The view used to render this drag pub view: AnyView, + + /// The value of the dragged item, to be dropped pub value: Box, + + /// This is used to render the dragged item in the same place + /// on the original element that the drag was initiated pub cursor_offset: Point, } @@ -1271,12 +1325,19 @@ pub struct AnyDrag { /// tooltip behavior on a custom element. Otherwise, use [Div::tooltip]. #[derive(Clone)] pub struct AnyTooltip { + /// The view used to display the tooltip pub view: AnyView, + + /// The offset from the cursor to use, relative to the parent view pub cursor_offset: Point, } +/// A keystroke event, and potentially the associated action #[derive(Debug)] pub struct KeystrokeEvent { + /// The keystroke that occurred pub keystroke: Keystroke, + + /// The action that was resolved for the keystroke, if any pub action: Option>, } diff --git a/crates/gpui/src/app/async_context.rs b/crates/gpui/src/app/async_context.rs index 6afb356e5e..1ee01d90df 100644 --- a/crates/gpui/src/app/async_context.rs +++ b/crates/gpui/src/app/async_context.rs @@ -7,6 +7,9 @@ use anyhow::{anyhow, Context as _}; use derive_more::{Deref, DerefMut}; use std::{future::Future, rc::Weak}; +/// An async-friendly version of [AppContext] with a static lifetime so it can be held across `await` points in async code. +/// You're provided with an instance when calling [AppContext::spawn], and you can also create one with [AppContext::to_async]. +/// Internally, this holds a weak reference to an `AppContext`, so its methods are fallible to protect against cases where the [AppContext] is dropped. #[derive(Clone)] pub struct AsyncAppContext { pub(crate) app: Weak, @@ -139,6 +142,8 @@ impl AsyncAppContext { self.foreground_executor.spawn(f(self.clone())) } + /// Determine whether global state of the specified type has been assigned. + /// Returns an error if the `AppContext` has been dropped. pub fn has_global(&self) -> Result { let app = self .app @@ -148,6 +153,9 @@ impl AsyncAppContext { Ok(app.has_global::()) } + /// Reads the global state of the specified type, passing it to the given callback. + /// Panics if no global state of the specified type has been assigned. + /// Returns an error if the `AppContext` has been dropped. pub fn read_global(&self, read: impl FnOnce(&G, &AppContext) -> R) -> Result { let app = self .app @@ -157,6 +165,9 @@ impl AsyncAppContext { Ok(read(app.global(), &app)) } + /// Reads the global state of the specified type, passing it to the given callback. + /// Similar to [read_global], but returns an error instead of panicking if no state of the specified type has been assigned. + /// Returns an error if no state of the specified type has been assigned the `AppContext` has been dropped. pub fn try_read_global( &self, read: impl FnOnce(&G, &AppContext) -> R, @@ -166,6 +177,8 @@ impl AsyncAppContext { Some(read(app.try_global()?, &app)) } + /// A convenience method for [AppContext::update_global] + /// for updating the global state of the specified type. pub fn update_global( &mut self, update: impl FnOnce(&mut G, &mut AppContext) -> R, @@ -179,6 +192,8 @@ impl AsyncAppContext { } } +/// A cloneable, owned handle to the application context, +/// composed with the window associated with the current task. #[derive(Clone, Deref, DerefMut)] pub struct AsyncWindowContext { #[deref] @@ -188,14 +203,16 @@ pub struct AsyncWindowContext { } impl AsyncWindowContext { - pub fn window_handle(&self) -> AnyWindowHandle { - self.window - } - pub(crate) fn new(app: AsyncAppContext, window: AnyWindowHandle) -> Self { Self { app, window } } + /// Get the handle of the window this context is associated with. + pub fn window_handle(&self) -> AnyWindowHandle { + self.window + } + + /// A convenience method for [WindowContext::update()] pub fn update( &mut self, update: impl FnOnce(AnyView, &mut WindowContext) -> R, @@ -203,10 +220,12 @@ impl AsyncWindowContext { self.app.update_window(self.window, update) } + /// A convenience method for [WindowContext::on_next_frame()] pub fn on_next_frame(&mut self, f: impl FnOnce(&mut WindowContext) + 'static) { self.window.update(self, |_, cx| cx.on_next_frame(f)).ok(); } + /// A convenience method for [AppContext::global()] pub fn read_global( &mut self, read: impl FnOnce(&G, &WindowContext) -> R, @@ -214,6 +233,8 @@ impl AsyncWindowContext { self.window.update(self, |_, cx| read(cx.global(), cx)) } + /// A convenience method for [AppContext::update_global()] + /// for updating the global state of the specified type. pub fn update_global( &mut self, update: impl FnOnce(&mut G, &mut WindowContext) -> R, @@ -224,6 +245,8 @@ impl AsyncWindowContext { self.window.update(self, |_, cx| cx.update_global(update)) } + /// Schedule a future to be executed on the main thread. This is used for collecting + /// the results of background tasks and updating the UI. pub fn spawn(&self, f: impl FnOnce(AsyncWindowContext) -> Fut) -> Task where Fut: Future + 'static, diff --git a/crates/gpui/src/app/entity_map.rs b/crates/gpui/src/app/entity_map.rs index 1e593caf98..d3f8a7ea89 100644 --- a/crates/gpui/src/app/entity_map.rs +++ b/crates/gpui/src/app/entity_map.rs @@ -31,6 +31,7 @@ impl From for EntityId { } impl EntityId { + /// Converts this entity id to a [u64] pub fn as_u64(self) -> u64 { self.0.as_ffi() } @@ -140,7 +141,7 @@ impl EntityMap { } } -pub struct Lease<'a, T> { +pub(crate) struct Lease<'a, T> { entity: Option>, pub model: &'a Model, entity_type: PhantomData, @@ -169,8 +170,9 @@ impl<'a, T> Drop for Lease<'a, T> { } #[derive(Deref, DerefMut)] -pub struct Slot(Model); +pub(crate) struct Slot(Model); +/// A dynamically typed reference to a model, which can be downcast into a `Model`. pub struct AnyModel { pub(crate) entity_id: EntityId, pub(crate) entity_type: TypeId, @@ -195,14 +197,17 @@ impl AnyModel { } } + /// Returns the id associated with this model. pub fn entity_id(&self) -> EntityId { self.entity_id } + /// Returns the [TypeId] associated with this model. pub fn entity_type(&self) -> TypeId { self.entity_type } + /// Converts this model handle into a weak variant, which does not prevent it from being released. pub fn downgrade(&self) -> AnyWeakModel { AnyWeakModel { entity_id: self.entity_id, @@ -211,6 +216,8 @@ impl AnyModel { } } + /// Converts this model handle into a strongly-typed model handle of the given type. + /// If this model handle is not of the specified type, returns itself as an error variant. pub fn downcast(self) -> Result, AnyModel> { if TypeId::of::() == self.entity_type { Ok(Model { @@ -307,6 +314,8 @@ impl std::fmt::Debug for AnyModel { } } +/// A strong, well typed reference to a struct which is managed +/// by GPUI #[derive(Deref, DerefMut)] pub struct Model { #[deref] @@ -368,10 +377,12 @@ impl Model { self.any_model } + /// Grab a reference to this entity from the context. pub fn read<'a>(&self, cx: &'a AppContext) -> &'a T { cx.entities.read(self) } + /// Read the entity referenced by this model with the given function. pub fn read_with( &self, cx: &C, @@ -437,6 +448,7 @@ impl PartialEq> for Model { } } +/// A type erased, weak reference to a model. #[derive(Clone)] pub struct AnyWeakModel { pub(crate) entity_id: EntityId, @@ -445,10 +457,12 @@ pub struct AnyWeakModel { } impl AnyWeakModel { + /// Get the entity ID associated with this weak reference. pub fn entity_id(&self) -> EntityId { self.entity_id } + /// Check if this weak handle can be upgraded, or if the model has already been dropped pub fn is_upgradable(&self) -> bool { let ref_count = self .entity_ref_counts @@ -458,6 +472,7 @@ impl AnyWeakModel { ref_count > 0 } + /// Upgrade this weak model reference to a strong reference. pub fn upgrade(&self) -> Option { let ref_counts = &self.entity_ref_counts.upgrade()?; let ref_counts = ref_counts.read(); @@ -485,6 +500,7 @@ impl AnyWeakModel { }) } + /// Assert that model referenced by this weak handle has been dropped. #[cfg(any(test, feature = "test-support"))] pub fn assert_dropped(&self) { self.entity_ref_counts @@ -527,6 +543,7 @@ impl PartialEq for AnyWeakModel { impl Eq for AnyWeakModel {} +/// A weak reference to a model of the given type. #[derive(Deref, DerefMut)] pub struct WeakModel { #[deref] @@ -617,12 +634,12 @@ lazy_static::lazy_static! { #[cfg(any(test, feature = "test-support"))] #[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq)] -pub struct HandleId { +pub(crate) struct HandleId { id: u64, // id of the handle itself, not the pointed at object } #[cfg(any(test, feature = "test-support"))] -pub struct LeakDetector { +pub(crate) struct LeakDetector { next_handle_id: u64, entity_handles: HashMap>>, } diff --git a/crates/gpui/src/app/model_context.rs b/crates/gpui/src/app/model_context.rs index 63db0ee1cb..e2aad9fee9 100644 --- a/crates/gpui/src/app/model_context.rs +++ b/crates/gpui/src/app/model_context.rs @@ -11,6 +11,7 @@ use std::{ future::Future, }; +/// The app context, with specialized behavior for the given model. #[derive(Deref, DerefMut)] pub struct ModelContext<'a, T> { #[deref] @@ -24,20 +25,24 @@ impl<'a, T: 'static> ModelContext<'a, T> { Self { app, model_state } } + /// The entity id of the model backing this context. pub fn entity_id(&self) -> EntityId { self.model_state.entity_id } + /// Returns a handle to the model belonging to this context. pub fn handle(&self) -> Model { self.weak_model() .upgrade() .expect("The entity must be alive if we have a model context") } + /// Returns a weak handle to the model belonging to this context. pub fn weak_model(&self) -> WeakModel { self.model_state.clone() } + /// Arranges for the given function to be called whenever [ModelContext::notify] or [ViewContext::notify] is called with the given model or view. pub fn observe( &mut self, entity: &E, @@ -59,6 +64,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { }) } + /// Subscribe to an event type from another model or view pub fn subscribe( &mut self, entity: &E, @@ -81,6 +87,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { }) } + /// Register a callback to be invoked when GPUI releases this model. pub fn on_release( &mut self, on_release: impl FnOnce(&mut T, &mut AppContext) + 'static, @@ -99,6 +106,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Register a callback to be run on the release of another model or view pub fn observe_release( &mut self, entity: &E, @@ -124,6 +132,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Register a callback to for updates to the given global pub fn observe_global( &mut self, mut f: impl FnMut(&mut T, &mut ModelContext<'_, T>) + 'static, @@ -140,6 +149,8 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Arrange for the given function to be invoked whenever the application is quit. + /// The future returned from this callback will be polled for up to [gpui::SHUTDOWN_TIMEOUT] until the app fully quits. pub fn on_app_quit( &mut self, mut on_quit: impl FnMut(&mut T, &mut ModelContext) -> Fut + 'static, @@ -165,6 +176,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Tell GPUI that this model has changed and observers of it should be notified. pub fn notify(&mut self) { if self .app @@ -177,6 +189,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { } } + /// Update the given global pub fn update_global(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R where G: 'static, @@ -187,6 +200,9 @@ impl<'a, T: 'static> ModelContext<'a, T> { result } + /// Spawn the future returned by the given function. + /// The function is provided a weak handle to the model owned by this context and a context that can be held across await points. + /// The returned task must be held or detached. pub fn spawn(&self, f: impl FnOnce(WeakModel, AsyncAppContext) -> Fut) -> Task where T: 'static, @@ -199,6 +215,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { } impl<'a, T> ModelContext<'a, T> { + /// Emit an event of the specified type, which can be handled by other entities that have subscribed via `subscribe` methods on their respective contexts. pub fn emit(&mut self, event: Evt) where T: EventEmitter, From 7a299e966afeb9eb5f0940ad9f22cdfcaa886a4c Mon Sep 17 00:00:00 2001 From: Mikayla Date: Wed, 17 Jan 2024 10:21:29 -0800 Subject: [PATCH 2/3] Document view crate co-authored-by: Nathan --- crates/gpui/src/view.rs | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/crates/gpui/src/view.rs b/crates/gpui/src/view.rs index 968fbbd94c..3701bbbd69 100644 --- a/crates/gpui/src/view.rs +++ b/crates/gpui/src/view.rs @@ -1,3 +1,5 @@ +#![deny(missing_docs)] + use crate::{ seal::Sealed, AnyElement, AnyModel, AnyWeakModel, AppContext, AvailableSpace, BorrowWindow, Bounds, ContentMask, Element, ElementId, Entity, EntityId, Flatten, FocusHandle, FocusableView, @@ -11,12 +13,16 @@ use std::{ hash::{Hash, Hasher}, }; +/// A view is a piece of state that can be presented on screen by implementing the [Render] trait. +/// Views implement [Element] and can composed with other views, and every window is created with a root view. pub struct View { + /// A view is just a [Model] whose type implements `Render`, and the model is accessible via this field. pub model: Model, } impl Sealed for View {} +#[doc(hidden)] pub struct AnyViewState { root_style: Style, cache_key: Option, @@ -58,6 +64,7 @@ impl View { Entity::downgrade(self) } + /// Update the view's state with the given function, which is passed a mutable reference and a context. pub fn update( &self, cx: &mut C, @@ -69,10 +76,12 @@ impl View { cx.update_view(self, f) } + /// Obtain a read-only reference to this view's state. pub fn read<'a>(&self, cx: &'a AppContext) -> &'a V { self.model.read(cx) } + /// Gets a [FocusHandle] for this view when its state implements [FocusableView]. pub fn focus_handle(&self, cx: &AppContext) -> FocusHandle where V: FocusableView, @@ -131,19 +140,24 @@ impl PartialEq for View { impl Eq for View {} +/// A weak variant of [View] which does not prevent the view from being released. pub struct WeakView { pub(crate) model: WeakModel, } impl WeakView { + /// Gets the entity id associated with this handle. pub fn entity_id(&self) -> EntityId { self.model.entity_id } + /// Obtain a strong handle for the view if it hasn't been released. pub fn upgrade(&self) -> Option> { Entity::upgrade_from(self) } + /// Update this view's state if it hasn't been released. + /// Returns an error if this view has been released. pub fn update( &self, cx: &mut C, @@ -157,9 +171,10 @@ impl WeakView { Ok(view.update(cx, f)).flatten() } + /// Assert that the view referenced by this handle has been released. #[cfg(any(test, feature = "test-support"))] - pub fn assert_dropped(&self) { - self.model.assert_dropped() + pub fn assert_released(&self) { + self.model.assert_released() } } @@ -185,6 +200,7 @@ impl PartialEq for WeakView { impl Eq for WeakView {} +/// A dynically-typed handle to a view, which can be downcast to a [View] for a specific type. #[derive(Clone, Debug)] pub struct AnyView { model: AnyModel, @@ -193,11 +209,15 @@ pub struct AnyView { } impl AnyView { + /// Indicate that this view should be cached when using it as an element. + /// When using this method, the view's previous layout and paint will be recycled from the previous frame if [ViewContext::notify] has not been called since it was rendered. + /// The one exception is when [WindowContext::refresh] is called, in which case caching is ignored. pub fn cached(mut self) -> Self { self.cache = true; self } + /// Convert this to a weak handle. pub fn downgrade(&self) -> AnyWeakView { AnyWeakView { model: self.model.downgrade(), @@ -205,6 +225,8 @@ impl AnyView { } } + /// Convert this to a [View] of a specific type. + /// If this handle does not contain a view of the specified type, returns itself in an `Err` variant. pub fn downcast(self) -> Result, Self> { match self.model.downcast() { Ok(model) => Ok(View { model }), @@ -216,10 +238,12 @@ impl AnyView { } } + /// Gets the [TypeId] of the underlying view. pub fn entity_type(&self) -> TypeId { self.model.entity_type } + /// Gets the entity id of this handle. pub fn entity_id(&self) -> EntityId { self.model.entity_id() } @@ -337,12 +361,14 @@ impl IntoElement for AnyView { } } +/// A weak, dynamically-typed view handle that does not prevent the view from being released. pub struct AnyWeakView { model: AnyWeakModel, layout: fn(&AnyView, &mut WindowContext) -> (LayoutId, AnyElement), } impl AnyWeakView { + /// Convert to a strongly-typed handle if the referenced view has not yet been released. pub fn upgrade(&self) -> Option { let model = self.model.upgrade()?; Some(AnyView { From 9eecda2dae1633568285adc27d37a2de2408120c Mon Sep 17 00:00:00 2001 From: Mikayla Date: Wed, 17 Jan 2024 10:23:46 -0800 Subject: [PATCH 3/3] Update method name and partially document platform crate co-authored-by: Nathan --- crates/collab/src/tests/following_tests.rs | 2 +- crates/gpui/src/app/entity_map.rs | 12 +++++----- crates/gpui/src/executor.rs | 3 ++- crates/gpui/src/platform.rs | 26 ++++++++++++++++----- crates/gpui/src/platform/mac/display.rs | 5 ---- crates/gpui/src/platform/test/display.rs | 4 ---- crates/gpui/src/scene.rs | 8 +++---- crates/gpui/src/text_system.rs | 2 +- crates/gpui/src/text_system/line_wrapper.rs | 2 +- crates/zed/src/zed.rs | 6 ++--- 10 files changed, 38 insertions(+), 32 deletions(-) diff --git a/crates/collab/src/tests/following_tests.rs b/crates/collab/src/tests/following_tests.rs index dc5488ebb3..af184d7d02 100644 --- a/crates/collab/src/tests/following_tests.rs +++ b/crates/collab/src/tests/following_tests.rs @@ -249,7 +249,7 @@ async fn test_basic_following( executor.run_until_parked(); cx_c.cx.update(|_| {}); - weak_workspace_c.assert_dropped(); + weak_workspace_c.assert_released(); // Clients A and B see that client B is following A, and client C is not present in the followers. executor.run_until_parked(); diff --git a/crates/gpui/src/app/entity_map.rs b/crates/gpui/src/app/entity_map.rs index d3f8a7ea89..7ab21a5477 100644 --- a/crates/gpui/src/app/entity_map.rs +++ b/crates/gpui/src/app/entity_map.rs @@ -281,7 +281,7 @@ impl Drop for AnyModel { entity_map .write() .leak_detector - .handle_dropped(self.entity_id, self.handle_id) + .handle_released(self.entity_id, self.handle_id) } } } @@ -500,15 +500,15 @@ impl AnyWeakModel { }) } - /// Assert that model referenced by this weak handle has been dropped. + /// Assert that model referenced by this weak handle has been released. #[cfg(any(test, feature = "test-support"))] - pub fn assert_dropped(&self) { + pub fn assert_released(&self) { self.entity_ref_counts .upgrade() .unwrap() .write() .leak_detector - .assert_dropped(self.entity_id); + .assert_released(self.entity_id); if self .entity_ref_counts @@ -658,12 +658,12 @@ impl LeakDetector { handle_id } - pub fn handle_dropped(&mut self, entity_id: EntityId, handle_id: HandleId) { + pub fn handle_released(&mut self, entity_id: EntityId, handle_id: HandleId) { let handles = self.entity_handles.entry(entity_id).or_default(); handles.remove(&handle_id); } - pub fn assert_dropped(&mut self, entity_id: EntityId) { + pub fn assert_released(&mut self, entity_id: EntityId) { let handles = self.entity_handles.entry(entity_id).or_default(); if !handles.is_empty() { for (_, backtrace) in handles { diff --git a/crates/gpui/src/executor.rs b/crates/gpui/src/executor.rs index fc60cb1ec6..8571c1ee57 100644 --- a/crates/gpui/src/executor.rs +++ b/crates/gpui/src/executor.rs @@ -109,9 +109,10 @@ type AnyFuture = Pin>>; /// BackgroundExecutor lets you run things on background threads. /// In production this is a thread pool with no ordering guarantees. -/// In tests this is simalated by running tasks one by one in a deterministic +/// In tests this is simulated by running tasks one by one in a deterministic /// (but arbitrary) order controlled by the `SEED` environment variable. impl BackgroundExecutor { + #[doc(hidden)] pub fn new(dispatcher: Arc) -> Self { Self { dispatcher } } diff --git a/crates/gpui/src/platform.rs b/crates/gpui/src/platform.rs index f165cd9c2b..7b260f1a7d 100644 --- a/crates/gpui/src/platform.rs +++ b/crates/gpui/src/platform.rs @@ -114,15 +114,20 @@ pub(crate) trait Platform: 'static { fn delete_credentials(&self, url: &str) -> Result<()>; } +/// A handle to a platform's display, e.g. a monitor or laptop screen. pub trait PlatformDisplay: Send + Sync + Debug { + /// Get the ID for this display fn id(&self) -> DisplayId; + /// Returns a stable identifier for this display that can be persisted and used /// across system restarts. fn uuid(&self) -> Result; - fn as_any(&self) -> &dyn Any; + + /// Get the bounds for this display fn bounds(&self) -> Bounds; } +/// An opaque identifier for a hardware display #[derive(PartialEq, Eq, Hash, Copy, Clone)] pub struct DisplayId(pub(crate) u32); @@ -134,7 +139,7 @@ impl Debug for DisplayId { unsafe impl Send for DisplayId {} -pub trait PlatformWindow { +pub(crate) trait PlatformWindow { fn bounds(&self) -> WindowBounds; fn content_size(&self) -> Size; fn scale_factor(&self) -> f32; @@ -175,6 +180,9 @@ pub trait PlatformWindow { } } +/// This type is public so that our test macro can generate and use it, but it should not +/// be considered part of our public API. +#[doc(hidden)] pub trait PlatformDispatcher: Send + Sync { fn is_main_thread(&self) -> bool; fn dispatch(&self, runnable: Runnable, label: Option); @@ -190,7 +198,7 @@ pub trait PlatformDispatcher: Send + Sync { } } -pub trait PlatformTextSystem: Send + Sync { +pub(crate) trait PlatformTextSystem: Send + Sync { fn add_fonts(&self, fonts: &[Arc>]) -> Result<()>; fn all_font_names(&self) -> Vec; fn font_id(&self, descriptor: &Font) -> Result; @@ -214,15 +222,21 @@ pub trait PlatformTextSystem: Send + Sync { ) -> Vec; } +/// Basic metadata about the current application and operating system. #[derive(Clone, Debug)] pub struct AppMetadata { + /// The name of the current operating system pub os_name: &'static str, + + /// The operating system's version pub os_version: Option, + + /// The current version of the application pub app_version: Option, } #[derive(PartialEq, Eq, Hash, Clone)] -pub enum AtlasKey { +pub(crate) enum AtlasKey { Glyph(RenderGlyphParams), Svg(RenderSvgParams), Image(RenderImageParams), @@ -262,7 +276,7 @@ impl From for AtlasKey { } } -pub trait PlatformAtlas: Send + Sync { +pub(crate) trait PlatformAtlas: Send + Sync { fn get_or_insert_with<'a>( &self, key: &AtlasKey, @@ -274,7 +288,7 @@ pub trait PlatformAtlas: Send + Sync { #[derive(Clone, Debug, PartialEq, Eq)] #[repr(C)] -pub struct AtlasTile { +pub(crate) struct AtlasTile { pub(crate) texture_id: AtlasTextureId, pub(crate) tile_id: TileId, pub(crate) bounds: Bounds, diff --git a/crates/gpui/src/platform/mac/display.rs b/crates/gpui/src/platform/mac/display.rs index 2b72c335c8..95ec83cd5a 100644 --- a/crates/gpui/src/platform/mac/display.rs +++ b/crates/gpui/src/platform/mac/display.rs @@ -11,7 +11,6 @@ use core_graphics::{ geometry::{CGPoint, CGRect, CGSize}, }; use objc::{msg_send, sel, sel_impl}; -use std::any::Any; use uuid::Uuid; #[derive(Debug)] @@ -154,10 +153,6 @@ impl PlatformDisplay for MacDisplay { ])) } - fn as_any(&self) -> &dyn Any { - self - } - fn bounds(&self) -> Bounds { unsafe { let native_bounds = CGDisplayBounds(self.0); diff --git a/crates/gpui/src/platform/test/display.rs b/crates/gpui/src/platform/test/display.rs index 68dbb0fdf3..838d600147 100644 --- a/crates/gpui/src/platform/test/display.rs +++ b/crates/gpui/src/platform/test/display.rs @@ -31,10 +31,6 @@ impl PlatformDisplay for TestDisplay { Ok(self.uuid) } - fn as_any(&self) -> &dyn std::any::Any { - unimplemented!() - } - fn bounds(&self) -> crate::Bounds { self.bounds } diff --git a/crates/gpui/src/scene.rs b/crates/gpui/src/scene.rs index de031704cd..b69c10c752 100644 --- a/crates/gpui/src/scene.rs +++ b/crates/gpui/src/scene.rs @@ -93,7 +93,7 @@ impl Scene { } } - pub fn insert(&mut self, order: &StackingOrder, primitive: impl Into) { + pub(crate) fn insert(&mut self, order: &StackingOrder, primitive: impl Into) { let primitive = primitive.into(); let clipped_bounds = primitive .bounds() @@ -440,7 +440,7 @@ pub enum PrimitiveKind { Surface, } -pub enum Primitive { +pub(crate) enum Primitive { Shadow(Shadow), Quad(Quad), Path(Path), @@ -589,7 +589,7 @@ impl From for Primitive { #[derive(Clone, Debug, Eq, PartialEq)] #[repr(C)] -pub struct MonochromeSprite { +pub(crate) struct MonochromeSprite { pub view_id: ViewId, pub layer_id: LayerId, pub order: DrawOrder, @@ -622,7 +622,7 @@ impl From for Primitive { #[derive(Clone, Debug, Eq, PartialEq)] #[repr(C)] -pub struct PolychromeSprite { +pub(crate) struct PolychromeSprite { pub view_id: ViewId, pub layer_id: LayerId, pub order: DrawOrder, diff --git a/crates/gpui/src/text_system.rs b/crates/gpui/src/text_system.rs index 34470aff02..27d216dd50 100644 --- a/crates/gpui/src/text_system.rs +++ b/crates/gpui/src/text_system.rs @@ -47,7 +47,7 @@ pub struct TextSystem { } impl TextSystem { - pub fn new(platform_text_system: Arc) -> Self { + pub(crate) fn new(platform_text_system: Arc) -> Self { TextSystem { line_layout_cache: Arc::new(LineLayoutCache::new(platform_text_system.clone())), platform_text_system, diff --git a/crates/gpui/src/text_system/line_wrapper.rs b/crates/gpui/src/text_system/line_wrapper.rs index f6963dbfd4..1c5b2a8f99 100644 --- a/crates/gpui/src/text_system/line_wrapper.rs +++ b/crates/gpui/src/text_system/line_wrapper.rs @@ -13,7 +13,7 @@ pub struct LineWrapper { impl LineWrapper { pub const MAX_INDENT: u32 = 256; - pub fn new( + pub(crate) fn new( font_id: FontId, font_size: Pixels, text_system: Arc, diff --git a/crates/zed/src/zed.rs b/crates/zed/src/zed.rs index bbe5e78109..afc06ad193 100644 --- a/crates/zed/src/zed.rs +++ b/crates/zed/src/zed.rs @@ -1809,9 +1809,9 @@ mod tests { assert!(workspace.active_item(cx).is_none()); }) .unwrap(); - editor_1.assert_dropped(); - editor_2.assert_dropped(); - buffer.assert_dropped(); + editor_1.assert_released(); + editor_2.assert_released(); + buffer.assert_released(); } #[gpui::test]