Skip to content
This repository has been archived by the owner on Sep 11, 2024. It is now read-only.

Fix some typos in Rust code, rustdoc, and markdown #233

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ COM specifies very little in the way of memory safety of COM based APIs. It is l

## The `unsafe` Keyword

It is a requirement for all usages of COM methods be marked as `unsafe`. This is required since at the time of declaring an interface, there is no way to ensure that any call to that interface will meet all of Rust's safety expectations.
It is a requirement for all usages of COM methods be marked as `unsafe`. This is required since at the time of declaring an interface, there is no way to ensure that any call to that interface will meet all of Rust's safety expectations.

## `&self`, `&mut self`, and `self`

All methods of a COM interface are required to take an unexclusive reference to self (`&self`). This reflects the reality that COM interfaces do not have exclusive access to the underlying class,and it does not take ownership (i.e., it is not responsible for the destruction) of the underlying class. As such if you're implementing a COM server, you will most likely need to use [interior mutability](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html) if you would like to mutate state in method calls.

## Example

It may be helpful to look at an example of a COM interface and what code gets generated to better understand its safety properties.
It may be helpful to look at an example of a COM interface and what code gets generated to better understand its safety properties.

We'll try to declare a minimum COM interface. This interface will seemingly do very little, but we'll explore what the programmer must ensure for this interface to be safe.

Expand All @@ -29,7 +29,7 @@ com::interfaces! {

This interface will expand to the following code.

```rust
```rust
// The interface is an FFI safe struct around a non-null pointer
#[derive(Debug)]
#[repr(transparent)]
Expand All @@ -41,7 +41,7 @@ pub struct IAnimal {
impl IAnimal {
// It is up to the programmer to ensure that the pointer contained
// in the interface is still valid.
// This is likely to be the case as interface automatically keeps
// This is likely to be the case as interface automatically keeps
// track of its reference count.
pub unsafe fn Eat(&self) -> HRESULT {
let interface_ptr = <Self as com::AbiTransferable>::get_abi(self);
Expand All @@ -53,13 +53,13 @@ impl IAnimal {
impl std::ops::Deref for IAnimal {
type Target = <IAnimal as com::Interface>::Super;
fn deref(&self) -> &Self::Target {
// This is safe because a valid reference to the child interface is exactly
// This is safe because a valid reference to the child interface is exactly
// equal to a valid reference to its parent interface.
unsafe { std::mem::transmute(self) }
}
}

// On drop the interface will call the IUknown::Release method
// On drop the interface will call the IUnknown::Release method
impl Drop for IAnimal {
fn drop(&mut self) {
// This is safe because we are calling `Release` when the interface handle is no
Expand Down
2 changes: 1 addition & 1 deletion examples/d2d-clock/src/clock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -670,7 +670,7 @@ interfaces! {
unsafe interface ID2D1Factory: IUnknown {
fn ReloadSystemMetrics(&self) -> HRESULT;
fn GetDesktopDpi(&self, dpi_x: *mut FLOAT, dpi_y: *mut FLOAT);
// ununsed functions
// unused functions
fn f0(&self);
fn f1(&self);
fn f2(&self);
Expand Down
10 changes: 5 additions & 5 deletions macros/support/src/class/class.rs
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ impl Class {
}
interfaces.push(interface);

let mut current = interfaces.last_mut().unwrap();
let current = interfaces.last_mut().unwrap();
fn parse_parens(buffer: &ParseBuffer, current: &mut Interface) -> syn::Result<()> {
while buffer.peek(syn::token::Paren) {
let contents;
Expand All @@ -161,7 +161,7 @@ impl Class {
Ok(())
}

parse_parens(input, &mut current)?;
parse_parens(input, current)?;

if !input.peek(syn::token::Brace) {
let _ = input.parse::<syn::Token!(,)>()?;
Expand Down Expand Up @@ -581,7 +581,7 @@ impl Interface {
quote::format_ident!("__{}_{}", offset, self.path.segments.last().unwrap().ident)
}

/// Creates an intialized VTable for the interface
/// Creates an initialized VTable for the interface
pub fn to_initialized_vtable_tokens(&self, class: &Class, offset: usize) -> TokenStream {
let class_name = &class.name;
let vtable_ident = self.vtable_ident();
Expand Down Expand Up @@ -683,11 +683,11 @@ impl Interface {
quote! {
{
// See https://github.com/rust-lang/rust/issues/86935
type IUknownVTable = <::com::interfaces::IUnknown as ::com::Interface>::VTable;
type IUnknownVTable = <::com::interfaces::IUnknown as ::com::Interface>::VTable;
#add_ref
#release
#query_interface
IUknownVTable {
IUnknownVTable {
AddRef,
Release,
QueryInterface,
Expand Down
6 changes: 3 additions & 3 deletions macros/support/src/interface/interface.rs
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ impl syn::parse::Parse for Interface {
if path.is_ident("doc") {
docs.push(attr);
} else if path.is_ident("uuid") {
let iid_str: ParenthsizedStr = syn::parse2(tokens.clone())?;
let iid_str: ParenthesizedStr = syn::parse2(tokens.clone())?;

iid = Some(IID::parse(&iid_str.lit)?);
} else {
Expand Down Expand Up @@ -173,11 +173,11 @@ mod keywords {
syn::custom_keyword!(interface);
}

struct ParenthsizedStr {
struct ParenthesizedStr {
lit: syn::LitStr,
}

impl syn::parse::Parse for ParenthsizedStr {
impl syn::parse::Parse for ParenthesizedStr {
fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
let lit;
syn::parenthesized!(lit in input);
Expand Down
4 changes: 2 additions & 2 deletions src/interface.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ use crate::sys::IID;
/// * it is `#[repr(C)]`
/// * the type only contains `extern "system" fn" definitions
///
/// The implementor must be a transparrently equivalent to a valid interface pointer
/// The implementor must be a transparently equivalent to a valid interface pointer
/// for the interface `T`. An interface pointer as the name suggests points to an
/// interface. A valid interface is itself trivial castable to a `*mut T::VTable`.
/// In other words, the implementing type must also be equal to `*mut *const T::VTable`
Expand All @@ -36,7 +36,7 @@ pub unsafe trait Interface: Sized + 'static {

/// Cast the COM interface pointer to a raw pointer
///
/// The returned pointer is only guranteed valid for as long
/// The returned pointer is only guaranteed valid for as long
/// as the reference to self id valid.
fn as_raw(&self) -> core::ptr::NonNull<core::ptr::NonNull<Self::VTable>> {
unsafe { core::mem::transmute_copy(self) }
Expand Down
2 changes: 1 addition & 1 deletion src/interfaces/mod.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! Common COM interfaces including IUknown and IClassFactory
//! Common COM interfaces including IUnknown and IClassFactory

pub mod iclass_factory;
pub mod iunknown;
Expand Down