Hsu Still
8 years ago
1 changed files with 10 additions and 10 deletions
Unified View
Diff Options
-
+10 -10docs/guides/concepts/events.md
+ 10
- 10
docs/guides/concepts/events.md
View File
| @@ -4,27 +4,27 @@ title: Working with Events | |||||
| Events in Discord.Net are consumed in a similar manner to the standard | Events in Discord.Net are consumed in a similar manner to the standard | ||||
| convention, with the exception that every event must be of the type | convention, with the exception that every event must be of the type | ||||
| `System.Threading.Tasks.Task`, and instead of using EventArgs, the | |||||
| `System.Threading.Tasks.Task` and instead of using `EventArgs`, the | |||||
| event's parameters are passed directly into the handler. | event's parameters are passed directly into the handler. | ||||
| This allows for events to be handled in an async context directly, | |||||
| instead of relying on async void. | |||||
| This allows for events to be handled in an async context directly | |||||
| instead of relying on async void`. | |||||
| ### Usage | ### Usage | ||||
| To receive data from an event, hook into it using C#'s delegate | To receive data from an event, hook into it using C#'s delegate | ||||
| event pattern. | event pattern. | ||||
| You may opt either to hook an event to an anonymous function (lambda) | |||||
| You may either opt to hook an event to an anonymous function (lambda) | |||||
| or a named function. | or a named function. | ||||
| ### Safety | ### Safety | ||||
| All events are designed to be thread-safe, in that events are executed | |||||
| synchronously off the gateway task, in the same context as the gateway | |||||
| All events are designed to be thread-safe in that events are executed | |||||
| synchronously off the gateway task in the same context as the gateway | |||||
| task. | task. | ||||
| As a side effect, this makes it possible to deadlock the gateway task, | |||||
| As a side effect, this makes it possible to deadlock the gateway task | |||||
| and kill a connection. As a general rule of thumb, any task that takes | and kill a connection. As a general rule of thumb, any task that takes | ||||
| longer than three seconds should **not** be awaited directly in the | longer than three seconds should **not** be awaited directly in the | ||||
| context of an event, but should be wrapped in a `Task.Run` or | context of an event, but should be wrapped in a `Task.Run` or | ||||
| @@ -33,7 +33,7 @@ offloaded to another task. | |||||
| This also means that you should not await a task that requests data | This also means that you should not await a task that requests data | ||||
| from Discord's gateway in the same context of an event. Since the | from Discord's gateway in the same context of an event. Since the | ||||
| gateway will wait on all invoked event handlers to finish before | gateway will wait on all invoked event handlers to finish before | ||||
| processing any additional data from the gateway, this will create | |||||
| processing any additional data from the gateway; this will create | |||||
| a deadlock that will be impossible to recover from. | a deadlock that will be impossible to recover from. | ||||
| Exceptions in commands will be swallowed by the gateway and logged out | Exceptions in commands will be swallowed by the gateway and logged out | ||||
| @@ -62,7 +62,7 @@ This pattern is typically only found on `EntityUpdated` events. | |||||
| An event handler with a signature of `Func<Cacheable, Entity, Task>` | An event handler with a signature of `Func<Cacheable, Entity, Task>` | ||||
| means that the `before` state of the entity was not provided by the | means that the `before` state of the entity was not provided by the | ||||
| API, so it can either be pulled from the client's cache, or | |||||
| API, so it can either be pulled from the client's cache or | |||||
| downloaded from the API. | downloaded from the API. | ||||
| See the documentation for [Cacheable] for more information on this | See the documentation for [Cacheable] for more information on this | ||||
| @@ -76,7 +76,7 @@ object. | |||||
| ### Tips | ### Tips | ||||
| Many events relating to a Message entity, e.g. `MessageUpdated` | |||||
| Many events relating to a Message entity (e.g. `MessageUpdated`) | |||||
| and `ReactionAdded` rely on the client's message cache, which is | and `ReactionAdded` rely on the client's message cache, which is | ||||
| **not** enabled by default. Set the `MessageCacheSize` flag in | **not** enabled by default. Set the `MessageCacheSize` flag in | ||||
| [DiscordSocketConfig] to enable it. | [DiscordSocketConfig] to enable it. | ||||