Skip to content

v0.5.0
Compare
Choose a tag to compare
released this 20 Jan 18:23
· 2237 commits to current since this release
v0.5.0
551f952

This release is a rewrite of the client and gateway internals with a minimal
amount of breaking changes for userland code. These changes are mainly to
prepare for Tokio and to reduce the number of atomic operations per received
event, reducing the number of atomic operations by roughly 85%. The framework
has also seen a rewrite, and is now centered around a trait-based design.

Thanks to the following for their contributions:

Upgrade Path

Per c:91c8ec4, the Guild::default_channel and
Guild::default_channel_guarenteed methods now return
Option<Arc<Mutex<GuildChannel>>> instead of Option<GuildChannel>. This
avoids a clone. To access the channel, you just have to retrieve a read or write
lock by doing guild.default_channel()?.read() or
guild.default_channel()?.write().

Per c:14b9222, there is a new Member::default_channel() function that
returns the default channel for the user. This no longer returns the channel
with the same ID as the guild itself, as this behaviour was changed by Discord.
A member's "default channel" is now the top-most channel that it has permission
to view. Accordingly, Guild::default_channel matches this behaviour.

Per c:93e0a42, the library now uses the parking_lot crate's Mutex and
RwLock implementations over the stdlib's. parking_lots implementations are
more efficient, do not poison due to lock drops on unwinding, and implement
eventual fairness.

To account for this, change all Mutex lock retrievals and RwLock read and
write lock retrievals to not unwrap. parking_lot's Mutex::lock,
RwLock::read, and RwLock::write don't return Results, unlike the stdlib's.

Per c:78c6df9, the Guild::features structfield is no longer a
Vec<Feature>. Discord adds guild features over time, which can cause guilds
with those new features to fail in deserialization. Instead, we're
future-proofing by making this a Vec<String>.

Per c:65e3279, the CreateEmbed builder's field and fields functions no
longer take a builder as the argument, and instead take 3 arguments. For
example, code like this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field(|f| f
            .name("Test field")
            .value("Test value")
            .inline(true))));

Would now be this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field("Test field", "Test value", true)))

Per c:ad0dcb3, shards can no longer have their afk property set, as this was
a leftover from user account support. This removes the afk parameter of the
Context::set_presence function, removal of the parameter from the
Shard::set_presence function, and the Shard::set_afk function.

Per c:b328b3e, the client::EventHandler no longer prefixes all trait methods
with on_. An implementation that looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::Message;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        // ...
    }
}

Now looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::channel::Message;

struct Handler;

impl EventHandler for Handler {
    fn message(&self, _: Context, msg: Message) {
        // ...
    }
}

(a note on the serenity::model::channel::Message import later.)

Per c:b19b031, Client::new returns a Result, as it now creates some
essential information on instantiation instead of deferring it to when a
connection is started. You can probably just unwrap this Result.

Per c:b8efeaf, c:d5a9aa8, and c:65233ad, the client and gateway internals
have been rebuilt to significantly reduce the number of atomic operations
(upwards of ~85%). This means that retrieval of shard information (like the
shard latency to the Discord gateway or the current connection status) are
retrieved via the encompassing ShardManager located on
the client. This can be inserted into the client's data structfield if you
need to access that information in event or framework command handlers. See
this example for more information. Additionally,
Context::quit to shutdown the shard no longer exists; go through the
ShardManager instead.

Per c:aad4744, the framework's Args::list function has been renamed to
Args::multiple for consistency.

Per c:f10b9d7, c:1fd652b, c:0aa55a2, the framework has been reworked to
be trait-based; thus as per c:f61816c, c:4e20277, allowed more useful functionality to commands.

Per c:05f6ed4, the client's close handle has been removed, in favour of
doing so through the ShardManager.

Per c:8c9baa7, the Guild::default_message_notifications, Guild::mfa_level,
PartialGuild::default_message_notifications, and PartialGuild::mfa_level
structfields are now enums to represent a stronger type, instead of u64s.

Per c:bcd16dd, the model module has been broken up: instead of a giant root
module full of imports, types have been moved to where they fit. For example,
the Message, Reaction, and Channel structs are now in the model::channel
module. The RichInvite, Member, Role, and MfaLevel types are now in
model::guild. Refer to the commit message or the
model module docs for more information.

Per c:be43836, the http::HttpError enum's InvalidRequest variant no longer
gives just the HTTP status code of the response. It now includes the full
Response instance.

Per c:2edba81, the builder re-export in the utils module no longer exists
after being there in deprecation for a long time. Please import it like so:

// old
use serenity::utils::builder;

// new
use serenity::builder;

Added

Fixed

Changed

Misc.

Assets 2
Loading