Skip to content
This repository has been archived by the owner on Apr 18, 2023. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
Improve the docs for I3_SYNC
I was confused by the previous state of the docs since I imagined that
there is still a race possible. Thus, the images are updated to
explicitly include the IPC reply from i3 (since that is an important
synchronisation component). I also tried to clarify some of the text.

Fixes: i3/i3#4365
Signed-off-by: Uli Schlachter <psychon@znc.in>
  • Loading branch information
psychon authored and stapelberg committed Mar 12, 2021
1 parent af2171d commit 8a5eac3
Show file tree
Hide file tree
Showing 5 changed files with 8 additions and 8 deletions.
Binary file modified docs/i3-sync-working.dia
Binary file not shown.
Binary file modified docs/i3-sync-working.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/i3-sync.dia
Binary file not shown.
Binary file modified docs/i3-sync.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 8 additions & 8 deletions docs/testsuite
Expand Up @@ -481,7 +481,7 @@ an i3 crash resulting in the testcase being unable to communicate with i3 via
IPC anymore.

[[i3_sync]]
== Appendix A: The i3 sync protocol
== Appendix A: The I3_SYNC protocol

Consider the following situation: You open two windows in your testcase, then
you use +focus left+ and want to verify that the X11 focus has been updated
Expand All @@ -499,9 +499,9 @@ is($x->input_focus, $left->id, 'left window focused');
However, the test fails. Sometimes. Apparently, there is a race condition in
your test. If you think about it, this is because you are using two different
pieces of software: You tell i3 to update focus, i3 confirms that, and then you
ask X11 to give you the current focus. There is a certain time i3 needs to
update the X11 state. If the testcase gets CPU time before X11 processed i3's
requests, the test will fail.
ask X11 to give you the current focus. There is a certain time that the X11
server needs to process the requests from i3. If the testcase's request for the
input focus is processed before i3's requests, the test will fail.

image::i3-sync.png["Diagram of the race condition", title="Diagram of the race condition"]

Expand Down Expand Up @@ -531,10 +531,10 @@ less robust.

The real solution for this problem is a mechanism which I call "the i3 sync
protocol". The idea is to send a request (which does not modify state) via X11
to i3 which will then be answered. Due to the request's position in the event
queue (*after* all previous events), you can be sure that by the time you
receive the reply, all other events have been dealt with by i3 (and, more
importantly, X11).
to i3 which will then be answered, again via X11. Because this answer is
generated via an X11 request, it will be sent to the X11 server *after* all
previous requests. Thus, you can be sure that by the time you receive the reply,
all other events have been dealt with by i3 (and, more importantly, X11).

image::i3-sync-working.png["Diagram of the i3 sync solution", title="Diagram of the i3 sync solution"]

Expand Down

0 comments on commit 8a5eac3

Please sign in to comment.