Expand description
Cookies are handles to future replies or errors from the X11 server.
When sending a request, you get back a cookie. There are different cookies for different kinds of requests.
For requests without a reply, you get a VoidCookie. Requests with a reply are represented
by a Cookie or a CookieWithFds if the reply also contains file descriptors.
Additionally, there are two special cases for requests which generate more than one reply:
ListFontsWithInfoCookie and [RecordEnableContextCookie].
Handling X11 errors
The X11 server can answer requests with an error packet for various reasons, e.g. because an invalid window ID was given. There are three options what can be done with errors:
- Errors can appear as X11 events in
wait_for_event()(in XCB, this is called “unchecked”) - Errors can be checked for locally after a request was sent (in XCB, this is called “checked”)
- Errors can be completely ignored (the closest analog in XCB would be
xcb_discard_reply())
There is an additional difference between requests with and without replies.
Requests without a reply
For requests that do not have a reply, you get an instance of VoidCookie after sending the
request. The different behaviors can be achieved via interacting with this cookie as foolows:
| What? | How? |
|---|---|
| Treat as events | Just drop the cookie |
| Check locally | VoidCookie::check |
| Ignore | VoidCookie::ignore_error |
Requests with a reply
For requests with a reply, an additional option is what should happen to the reply. You can get the reply, but any errors are still treated as events. This allows to centralise X11 error handling a bit in case you only want to log errors.
The following things can be done with the Cookie that you get after sending a request with an
error.
| Reply | Errors locally/ignored | Errors as events |
|---|---|---|
| Get | Cookie::reply | Cookie::reply_unchecked |
| Ignore | Cookie::discard_reply_and_errors | Just drop the cookie |
Structs
- A handle to a response from the X11 server.
- A handle to a response containing
RawFdfrom the X11 server. - A handle to the replies to a
ListFontsWithInforequest. - A handle to a possible error from the X11 server.