Nexus Express Way

Nexus simplifies shard management with Nexus Express Way, a lightweight event manager for Discord shards. This tool empowers Nexus to retrieve shards or perform tasks on specific shards, even before those shards become available. Initially designed for command synchronization, Nexus Express Way enables developers to poll shards or perform tasks on shards anywhere, with the framework automatically handling shard availability and related tasks.

Simplified Shard Management

Nexus Express Way isn't solely available for the internal working of the framework; developers can also leverage it. To explore the API, refer to NexusExpress.kt. Here's an example of its usage:

// Broadcast sends the event to all available shards, without waiting for shards that aren't available at the time of execution.
Nexus.express.broadcast { shard -> ... }
// Queue waits for the specified shard to become available and sends the event when it is ready (if it isn't already).
Nexus.express.queue(shard = 0) { shard -> ... }

// Awaits (returns a CompletableFuture) for the shard, server, or any available shard to become available. Internally, this method uses the `queue` method and wraps it with a CompletableFuture. This is recommended as it also handles failed events by default.
val shard = Nexus.express.await(shard = 0)
val server = Nexus.express.await(server = 0L)
val shard = Nexus.express.awaitAvailable()

Typically, the queue events don't inform you when an event is canceled, times out, or faces related issues. To monitor these states, you need to create a signal listener as follows:

val event = Nexus.express.queue(shard = 0) { shard -> ... }
event.addStatusChangeListener { event: NexusExpressEvent, oldStatus: NexusExpressEventStatus, newStatus: NexusExpressEventStatus -> 
    // Implement handling here, such as checking if the new status is cancelled, then taking appropriate action.
}

You can also cancel a non-running event. This requires the event to be in WAITING state, which can be tricky to catch, as all events execute immediately if the shard is already available, which in later stages of the bot, the shard should already be available. To cancel an event that's still in WAITING state, you can use the .cancel() method:

val event = Nexus.express.queue(shard = 0) { shard -> ... }
event.cancel()

Costs & Overhead, Internal Design

Nexus Express Way is designed to operate three threads (or coroutines, if you've configured the framework for coroutines, read more) per shard during its initial availability. Note the "initial availability," which means it utilizes three threads per shard only when the shard first becomes available. These threads handle the three initial queues: the global queue, the predicate queue, and the local queue. During this processing, all events in each queue are polled and processed until the queue is empty. All events are still processed asynchronously.

It's important to understand that all events are asynchronous, which may involve the use of a thread or coroutine. However, by default, Nexus utilizes its thread pool. For Kotlin users, switching the framework's internal launcher to coroutines is recommended, as it reduces costs. Generally, there is minimal performance difference when using Express Way, as once the shard becomes available, all events are processed immediately without passing through a queue.

For further insights, you can explore NexusExpressCore.kt to learn more about the internal code of NexusExpress.