[twilight-model]: consider using Cow<'static, str> and Cow<'static, [T]> for various fields

[BastiDood]

Currently, most string fields in the twilight-model crate take in an owned String. This is fine, but I realize that for most cases, a plain &'static str is sufficient. The mandatory heap allocation (from the String) is thus usually unnecessary. Consider this example with rich embeds (using 0.10.2):

use twilight_model::channel::embed::{Embed, EmbedField};
let embed = Embed {
    // Most fields omitted for brevity...
    title: Some(String::from("A super cool rich embed!")),
    description: Some(String::from("Some super cool description, too...")),
    kind: String::from("rich"),
    fields: Vec::from([EmbedField {
        name: String::from("`help`"),
        value: String::from("This is the help command."),
        inline: false,
    }]),
};

Hopefully, it is apparent from my example that there are too many String allocations here, where plain &'static str slices will suffice. We can also note the Vec allocation, which is arguably unnecessary since we know for certain that there is only one element.¹

Of course, this example also applies to other areas of the library. Rich embeds are just one particular instance.

A Possible Solution

In line with the goal to reduce heap allocations, I propose that we consider using the alloc::borrow::Cow smart pointer instead of String and Vec. The Cow smart pointer employs "copy-on-write" semantics so that heap allocations are kept at a minimum.

Now, I understand that ownership is one of the primary reasons why String and Vec were chosen. After all, it becomes rather cumbersome to use many of the data models if explicit lifetimes were required—though, I personally wouldn't be totally against this proposition.

Anyway, a good compromise is to use a Cow<'static, str> and a Cow<'static, [T]> (for all types T). Observe that the 'static lifetime specifier enforces that the data model (practically) "owns" the slice, even though it is technically borrowed. Therefore, the enclosing struct need not be generic over arbitrary lifetimes.

use alloc::borrow::Cow;
struct User {
    /// The `'static` lifetime allows us to treat this `struct`
    /// _as if_ it owns a string. There is no need to have the
    /// `User` be generic over arbitrary lifetimes. Hooray! 🥳
    name: Cow<'static, str>,
    bytes: Cow<'static, [u8]>,
}

This gives the user extra flexibility on whether to use a &'static str or a regular String (e.g. in cases where string interpolation is necessary). Consider the same rich embed example from earlier:

use alloc::borrow::Cow;
use twilight_model::channel::embed::{Embed, EmbedField};
let embed = Embed {
    // Most fields omitted for brevity...
    title: Some(Cow::Borrowed("A super cool rich embed!")),
    description: Some(Cow::Borrowed("Some super cool description, too...")),
    kind: Cow::Borrowed("rich"),
    fields: Cow::Borrowed(&[EmbedField {
        name: Cow::Borrowed("`help`"),
        value: Cow::Borrowed("This is the help command."),
        inline: false,
    }]),
};

It is important to note that there are now zero allocations here. Both the Vec and String have been removed in favor of their 'static counterparts. In case string interpolation or dynamic arrays are needed, one may use Cow::Owned variant instead (containing the appropriate String or Vec). Consider this other example for mixed usage:

use alloc::borrow::Cow;
use twilight_model::channel::embed::{Embed, EmbedField};

// Example dynamic data
let name: Box<str> = get_username_from_somewhere();
let num: u32 = get_number_from_somewhere();

let embed = Embed {
    // Most fields omitted for brevity...
    title: Some(Cow::Owned(format!("Your number is: {num}."))),
    description: Some(Cow::Borrowed("Some static description, too...")),
    kind: Cow::Borrowed("rich"),
    fields: Cow::Borrowed(&[EmbedField {
        name: Cow::Borrowed("`help`"),
        value: Cow::Owned(format!("Hi, {name}. This is the help command.")),
        inline: false,
    }]),
};

Suggestions for Migration

Most builder setters and utilities from this library rely on the fact that the intended target field is a String or a Vec. I'm aware that it will be rather tedious to convert all of the parameters to their Cow-equivalent. Luckily, generics come to the rescue! Suppose we intend to migrate to the Cow smart pointer for the builders in the twilight-util crate:

+ // We may consider using type aliases for convenience.
+ type DiscordStr = alloc::borrow::Cow<'static, str>;

impl EmbedFieldBuilder {
-    pub fn new(name: impl Into<String>, value: impl Into<String>) -> Self {
+    pub fn new(name: impl Into<DiscordStr>, value: impl Into<DiscordStr>) -> Self {
        todo!()
    }
}

The standard library already provides the convenience From and Into implementations. From the user's perspective, constructing an EmbedFieldBuilder still works the same as before thanks to the standard conversions.

// The generics should evaluate to the `Cow::<'static, str>::Borrowed` variant.
let field = EmbedFieldBuilder::new("`help`", "This is the help command.");

Footnotes

1. In addition to the heap allocation, extra copies of the data also occur due to the fact that the String::from implementation simply copies the bytes from the &'static str into the new allocation. The Vec works in a similar fashion. ↩

[PyroTechniac]

We use heap allocated strings because a lot of the events are received as well as sent, so the String either A. has to last as long as it's received event or B. has to be heap allocated.

[BastiDood]

... either A. has to last as long as it's received event or B. has to be heap allocated.

Ah, that's the cool thing about Cow<'static, T>! By hard-coding the 'static lifetime, we are only allowing values that live for the duration of the program (e.g. hard-coded strings that are embedded in the binary itself). In addition, the Cow::Owned variant grants us the flexibility of using the regular (heap-allocated) String as well. It's kinda like the best of both worlds.

[itohatweb]

Cow<'static, str> is bigger in memory tho.

According to std::mem::size_of:

Type	Size
Cow<'static, str>	32
String	24
&str	16

[BastiDood]

Why 32 bytes?

That is true. Please correct me if I'm wrong, but I presume that the extra bits come from the fact that Cow<'_, str> is a union between String and &str. Hence, since String takes up the most physical space among the two, then the union must have at least 24 bytes. The 8 bytes remaining are for the discriminator/tag for the union.

Why is this not an issue?

A core assumption I am making here is that most usage of String are actually just hard-coded &'static str slices that are already embedded in the binary—zero heap allocation necessary as illustrated by my examples above. If we impose that all strings must be heap-allocated (as in the current state of the library), then &'static str slices will have to be copied from .rodata (or elsewhere in read-only memory) into the heap and then wrapped in a String.

Arguably, this has greater implications for memory than the Cow being 32 bytes. At least for the Cow, a single &'static str will not have to be entirely copied into the heap anymore. Instead, only its length and its pointer to the .rodata are passed around. On the contrary, imposing String means that all &'static str must be entirely copied—despite already being embedded in the binary.

A concrete example

Consider a situation where we have a string with 10 or so ASCII characters (for the sake of argument). With String, we have to copy all those 10 bytes to the heap and then wrap the allocation in a String. Observe that there is a considerable amount of duplicated data here. The bytes are already in .rodata (or elsewhere in read-only memory), but we impose that they be copied into the heap.

Now, this is not the case for Cow<'static, str>. Although it takes up just 8 more bytes on the stack (than a regular String), there will be zero string duplication here. The Cow will simply point to the appropriate read-only allocation in the binary.

But in case we do need dynamic allocation, Cow grants us that flexibility with its Owned variant, which is pretty cool! All things considered, I would say that the extra 8 bytes are a fair trade-off. After all, modern computers prefer working with 32- or 64-bit data, anyway. 😅

[PyroTechniac]

This could be useful for things such as Embed, or data we send to discord, however models such as User and Message won't be benefitted as we don't normally construct those to be sent, just received

[BastiDood]

I agree. 👍

Though, it does come with the downside that the API becomes less consistent with strings. I'm not sure how you feel about that from a UX perspective. Personally, I can live with it, but some may argue that we may as well go all-or-nothing here.