|
| 1 | +# Why a Bridge Module? |
| 2 | + |
| 3 | +The `swift-bridge` project provides direct support for expressing the Rust+Swift FFI boundary using one or more bridge modules such as: |
| 4 | +```rust |
| 5 | +#[swift_bridge::bridge] |
| 6 | +mod ffi { |
| 7 | + extern "Rust" { |
| 8 | + fn generate_random_number() -> u32; |
| 9 | + } |
| 10 | +} |
| 11 | + |
| 12 | +fn generate_random_number() -> u32 { |
| 13 | + rand::random() |
| 14 | +} |
| 15 | +``` |
| 16 | + |
| 17 | +`swift-bridge`'s original maintainer wrote `swift-bridge` for use in a cross platform application where he preferred to keep his FFI code separate from his application code. |
| 18 | +He believed that this separation would reduce the likelihood of him biasing his core application's design towards types that were easier to bridge to Swift. |
| 19 | + |
| 20 | +While in the future `swift-bridge` may decide to directly support other approaches to defining FFI boundaries, at present only the bridge module approach is directly supported. |
| 21 | + |
| 22 | +Users with other needs can write wrappers around `swift-bridge` to expose alternative frontends. |
| 23 | + |
| 24 | +The `examples/without-a-bridge-macro` example demonstrates how to reuse `swift-bridge`'s code generation facilities without using a bridge module. |
| 25 | + |
| 26 | +## Inline Annotations |
| 27 | + |
| 28 | +The main alternative to the bridge module design would be to support inline annotations where one could describe their FFI boundary by annotating their Rust types. |
| 29 | + |
| 30 | +For instance a user might wish to expose their Rust banking code to Swift using an approach such as: |
| 31 | +```rust |
| 32 | +// IMAGINARY CODE. WE DO NOT PROVIDE A WAY TO DO THIS. |
| 33 | + |
| 34 | +#[derive(Swift)] |
| 35 | +pub struct BankAccount { |
| 36 | + balance: u32 |
| 37 | +} |
| 38 | + |
| 39 | +#[swift_bridge::bridge] |
| 40 | +pub fn create_bank_account() -> BankAccount { |
| 41 | + BankAccount { |
| 42 | + balance: 0 |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +`swift-bridge` aims to be a low-level library that generates far more efficient FFI code than a human would write and maintain themselves. |
| 48 | + |
| 49 | +The more information that `swift-bridge` has at compile time, the more efficient code it can generate. |
| 50 | + |
| 51 | +Let's explore an example of bridging a `UserId` type, along with a function that returns the latest `UserId` in the system. |
| 52 | + |
| 53 | +```rust |
| 54 | +type Uuid = [u8; 16]; |
| 55 | + |
| 56 | +#[derive(Copy)] |
| 57 | +struct UserId(Uuid); |
| 58 | + |
| 59 | +pub fn get_latest_user() -> Result<UserId, ()> { |
| 60 | + Ok(UserId([123; 16])) |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +In our example, the `UserId` is a wrapper around a 16 byte UUID. |
| 65 | + |
| 66 | +Exposing this as a bridge module might look like: |
| 67 | + |
| 68 | +```rust |
| 69 | +#[swift_bridge::bridge] |
| 70 | +mod ffi { |
| 71 | + extern "Rust" { |
| 72 | + #[swift_bridge(Copy(16))] |
| 73 | + type UserId; |
| 74 | + |
| 75 | + fn get_latest_user() -> UserId; |
| 76 | + } |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +Exposing the `UserId` using inlined annotation might look something like: |
| 81 | + |
| 82 | +```rust |
| 83 | +// WE DO NOT SUPPORT THIS |
| 84 | + |
| 85 | +type Uuid = [u8; 16]; |
| 86 | + |
| 87 | +#[derive(Copy, ExposeToSwift)] |
| 88 | +struct UserId(Uuid); |
| 89 | + |
| 90 | +#[swift_bridge::bridge] |
| 91 | +pub fn get_latest_user() -> Result<UserId, ()> { |
| 92 | + UserId([123; 16]) |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +In the bridge module example, `swift-bridge` knows at compile time that the `UserId` implements `Copy` and has a size of `16` bytes. |
| 97 | + |
| 98 | +In the inlined annotation example, however, `swift-bridge` does not know the `UserId` implements `Copy`. |
| 99 | + |
| 100 | +While it would be possible to inline this information, it would mean that users would need to remember to inline this information |
| 101 | +on every function that used the `UserId`. |
| 102 | +```rust |
| 103 | +// WE DO NOT SUPPORT THIS |
| 104 | + |
| 105 | +#[swift_bridge::bridge] |
| 106 | +#[swift_bridge(UserId impl Copy(16))] |
| 107 | +pub fn get_latest_user() -> Result<UserId, ()> { |
| 108 | + UserId([123; 16]) |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +We expect that users would find it difficult to remember to repeat such annotations, meaning users would tend to expose less efficient bridges |
| 113 | +than they otherwise could have. |
| 114 | + |
| 115 | +If `swift-bridge` does not know that the `UserId` implements `Copy`, it will need to generate code like: |
| 116 | +```rust |
| 117 | +pub extern "C" fn __swift_bridge__get_latest_user() -> *mut UserId { |
| 118 | + let user = get_latest_user(); |
| 119 | + match user { |
| 120 | + Ok(user) => Box::new(Box::into_raw(user)), |
| 121 | + Err(()) => std::ptr::null_mut() as *mut UserId, |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +Whereas if `swift-bridge` knows that the `UserId` implements `Copy`, it might be able to avoid an allocation by generating code such as: |
| 127 | +```rust |
| 128 | +/// `swift-bridge` could conceivably generate code like this to bridge |
| 129 | +/// a `Result<UserId, ()>`. |
| 130 | +/// Here we use a 17 byte array where the first byte indicates `Ok` or `Err` |
| 131 | +/// and, then `Ok`, the last 16 bytes hold the `UserId`. |
| 132 | +/// We expect this to be more performant than the boxing in the previous |
| 133 | +/// example codegen. |
| 134 | +pub extern "C" fn __swift_bridge__get_latest_user() -> [u8; 17] { |
| 135 | + let mut bytes: [u8; 17] = [0; 17]; |
| 136 | + |
| 137 | + let user = get_latest_user(); |
| 138 | + |
| 139 | + match user { |
| 140 | + Ok(user) => { |
| 141 | + let user_bytes: [u8; 16] = unsafe { std::mem::transmute(user) }; |
| 142 | + (&mut bytes[1..]).copy_from_slice(&user_bytes); |
| 143 | + |
| 144 | + bytes[0] = 255; |
| 145 | + bytes |
| 146 | + } |
| 147 | + Err(()) => { |
| 148 | + bytes |
| 149 | + } |
| 150 | + } |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | +More generally, the more information that `swift-bridge` has about the FFI interface, the more optimized code it can generate. |
| 155 | +The bridge module design steers users towards providing more information to `swift-bridge`, which we expect to lead to more efficient |
| 156 | +applications. |
| 157 | + |
| 158 | +Users that do not need such efficiency can explore reusing `swift-bridge` in alternative projects that better meet their needs. |
0 commit comments