]> git.sur5r.net Git - i3/i3/blob - docs/testsuite
i3-msg: check reply in quiet mode
[i3/i3] / docs / testsuite
1 i3 testsuite
2 ============
3 Michael Stapelberg <michael@i3wm.org>
4 September 2012
5
6 This document explains how the i3 testsuite works, how to use it and extend it.
7 It is targeted at developers who not necessarily have been doing testing before
8 or have not been testing in Perl before. In general, the testsuite is not of
9 interest for end users.
10
11
12 == Introduction
13
14 The i3 testsuite is a collection of files which contain testcases for various
15 i3 features. Some of them test if a certain workflow works correctly (moving
16 windows, focus behaviour, …). Others are regression tests and contain code
17 which previously made i3 crash or lead to unexpected behaviour. They then check
18 if i3 still runs (meaning it did not crash) and if it handled everything
19 correctly.
20
21 The goal of having these tests is to automatically find problems and to
22 automatically get a feel for whether a change in the source code breaks any
23 existing feature. After every modification of the i3 sourcecode, the developer
24 should run the full testsuite. If one of the tests fails, the corresponding
25 problem should be fixed (or, in some cases, the testcase has to be modified).
26 For every bugreport, a testcase should be written to test the correct
27 behaviour. Initially, it will fail, but after fixing the bug, it will pass.
28 This ensures (or increases the chance) that bugs which have been fixed once
29 will never be found again.
30
31 Also, when implementing a new feature, a testcase might be a good way to be
32 able to easily test if the feature is working correctly. Many developers will
33 test manually if everything works. Having a testcase not only helps you with
34 that, but it will also be useful for every future change.
35
36 == Relevant documentation
37
38 Apart from this document, you should also have a look at:
39
40 1. The "Modern Perl" book, which can be found at
41    http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf
42 2. The latest Perl documentation of the "i3test" (general testcase setup) and
43    "i3test::Test" (additional test instructions) modules:
44    https://build.i3wm.org/docs/lib-i3test.html respectively
45    https://build.i3wm.org/docs/lib-i3test-test.html
46 3. The latest documentation on i3’s IPC interface:
47    https://build.i3wm.org/docs/ipc.html
48
49 == Implementation
50
51 For several reasons, the i3 testsuite has been implemented in Perl:
52
53 1. Perl has a long tradition of testing. Every popular/bigger Perl module which
54    you can find on CPAN will not only come with documentation, but also with
55    tests. Therefore, the available infrastructure for tests is comprehensive.
56    See for example the excellent http://search.cpan.org/perldoc?Test::More
57    and the referenced http://search.cpan.org/perldoc?Test::Tutorial.
58
59 2. Perl is widely available and has a well-working package infrastructure.
60 3. The author is familiar with Perl :).
61 4. It is a good idea to use a different language for the tests than the
62    implementation itself.
63
64 Please do not start programming language flamewars at this point.
65
66 === Installing the dependencies
67
68 As usual with Perl programs, the testsuite ships with a +Makefile.PL+.
69 This file specifies which Perl modules the testsuite depends on and can be used
70 to install all of them.
71
72 Perl modules are distributed via CPAN, and there is the official, standard CPAN
73 client, simply called +cpan+. It comes with every Perl installation and can be
74 used to install the testsuite. Many users prefer to use the more modern
75 +cpanminus+ instead, though (because it asks no questions and just works):
76
77 The tests additionally require +Xephyr(1)+ to run a nested X server. Install
78 +xserver-xephyr+ on Debian or +xorg-server-xephyr+ on Arch Linux.
79
80 .Installing testsuite dependencies using cpanminus (preferred)
81 --------------------------------------------------------------------------------
82 $ cd ~/i3/testcases
83 $ sudo apt-get install cpanminus
84 $ sudo cpanm .
85 $ cd ~/i3/AnyEvent-I3
86 $ sudo cpanm Module::Install
87 $ sudo cpanm .
88 --------------------------------------------------------------------------------
89
90 If you don’t want to use cpanminus for some reason, the same works with cpan:
91
92 .Installing testsuite dependencies using cpan
93 --------------------------------------------------------------------------------
94 $ cd ~/i3/testcases
95 $ sudo cpan .
96 $ cd ~/i3/AnyEvent-I3
97 $ sudo cpan Module::Install
98 $ sudo cpan .
99 --------------------------------------------------------------------------------
100
101 In case you don’t have root permissions, you can also install into your home
102 directory, see https://michael.stapelberg.de/cpan/
103
104 === Mechanisms
105
106 ==== Script: complete-run
107
108 The testcases are run by a script called +complete-run.pl+. It runs all
109 testcases by default, but you can be more specific and let it only run one or
110 more testcases. Also, it takes care of starting up a separate instance of i3
111 with an appropriate configuration file and creates a folder for each run
112 containing the appropriate i3 logfile for each testcase. The latest folder can
113 always be found under the symlink +latest/+. Unless told differently, it will
114 run the tests on a separate X server instance (using Xephyr).
115
116 Xephyr will open a window where you can inspect the running test. By default,
117 tests are run under Xvfb.
118
119 .Example invocation of +complete-run.pl+
120 ---------------------------------------
121 $ cd ~/i3
122
123 $ autoreconf -fi
124
125 $ mkdir -p build && cd build
126
127 $ ../configure
128
129 $ make -j8
130 # output omitted because it is very long
131
132 $ cd testcases
133
134 $ ./complete-run.pl
135 # output omitted because it is very long
136 All tests successful.
137 Files=78, Tests=734, 27 wallclock secs ( 0.38 usr  0.48 sys + 17.65 cusr  3.21 csys = 21.72 CPU)
138 Result: PASS
139
140 $ ./complete-run.pl t/04-floating.t
141 [:3] i3 startup: took 0.07s, status = 1
142 [:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t
143 [:3] t/04-floating.t finished
144 [:3] killing i3
145 output for t/04-floating.t:
146 ok 1 - use X11::XCB::Window;
147 ok 2 - The object isa X11::XCB::Window
148 ok 3 - Window is mapped
149 ok 4 - i3 raised the width to 75
150 ok 5 - i3 raised the height to 50
151 ok 6 - i3 did not map it to (0x0)
152 ok 7 - The object isa X11::XCB::Window
153 ok 8 - i3 let the width at 80
154 ok 9 - i3 let the height at 90
155 ok 10 - i3 mapped it to x=1
156 ok 11 - i3 mapped it to y=18
157 ok 12 - The object isa X11::XCB::Window
158 ok 13 - i3 let the width at 80
159 ok 14 - i3 let the height at 90
160 1..14
161
162 All tests successful.
163 Files=1, Tests=14,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.19 cusr  0.03 csys =  0.23 CPU)
164 Result: PASS
165
166 $ less latest/i3-log-for-04-floating.t
167 ----------------------------------------
168
169 If your attempt to run the tests with a bare call to ./complete-run.pl fails, try this:
170
171 ---------------------------------------------------
172 $ ./complete-run.pl --parallel=1 --keep-xserver-output
173 ---------------------------------------------------
174
175 This will show the output of Xephyr, which is the X server implementation we
176 use for testing.
177
178 ===== make command: +make check+
179 Make check runs the i3 testsuite.
180 You can still use ./testcases/complete-run.pl to get the interactive progress output.
181
182 .Example invocation of +make check+
183 ---------------------------------------
184 $ cd ~/i3
185
186 $ autoreconf -fi
187
188 $ mkdir -p build && cd build
189
190 $ ../configure
191
192 $ make -j8
193 # output omitted because it is very long
194
195 $ make check
196 # output omitted because it is very long
197 PASS: testcases/complete-run.pl
198 ============================================================================
199 Testsuite summary for i3 4.13
200 ============================================================================
201 # TOTAL: 1
202 # PASS:  1
203 # SKIP:  0
204 # XFAIL: 0
205 # FAIL:  0
206 # XPASS: 0
207 # ERROR: 0
208 ============================================================================
209
210 $ less test-suite.log
211 ----------------------------------------
212
213 ==== Coverage testing
214
215 Coverage testing is possible with +lcov+, the front-end for GCC's coverage
216 testing tool +gcov+. The testcases can generate a nice html report that tells
217 you which functions and lines were covered during a run of the tests. You can
218 use this tool to judge how effective your tests are.
219
220 To use test coverage tools, first compile with coverage enabled.
221
222 ---------------------------------------------------
223 COVERAGE=1 make
224 ---------------------------------------------------
225
226 Then run the tests with the +--coverage-testing+ flag.
227
228 ---------------------------------------------------
229 ./complete-run.pl --coverage-testing
230 ---------------------------------------------------
231
232 Then open +latest/i3-coverage/index.html+ in your web browser.
233
234 ==== IPC interface
235
236 The testsuite makes extensive use of the IPC (Inter-Process Communication)
237 interface which i3 provides. It is used for the startup process of i3, for
238 terminating it cleanly and (most importantly) for modifying and getting the
239 current state (layout tree).
240
241 See [https://i3wm.org/docs/ipc.html] for documentation on the IPC interface.
242
243 ==== X11::XCB
244
245 In order to open new windows, change attributes, get events, etc., the
246 testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl
247 module which uses the XCB protocol description to generate Perl bindings to
248 X11. They work in a very similar way to libxcb (which i3 uses) and provide
249 relatively high-level interfaces (objects such as +X11::XCB::Window+) as well as
250 access to the low-level interface, which is very useful when testing a window
251 manager.
252
253 === Filesystem structure
254
255 In the git root of i3, the testcases live in the folder +testcases+. This
256 folder contains the +complete-run.pl+ and a base configuration file which will
257 be used for the tests. The different testcases (their file extension is .t, not
258 .pl) themselves can be found in the conventionally named subfolder +t+:
259
260 .Filesystem structure
261 --------------------------------------------
262 ├── testcases
263 │   ├── complete-run.pl
264 │   ├── i3-test.config
265 │   ├── lib
266 │   │   ├── i3test.pm
267 │   │   ├── SocketActivation.pm
268 │   │   └── StartXDummy.pm
269 │   ├── t
270 │   │   ├── 00-load.t
271 │   │   ├── 01-tile.t
272 │   │   ├── 02-fullscreen.t
273 │   │   ├── ...
274 │   │   ├── omitted for brevity
275 │   │   ├── ...
276 │   │   └── 74-regress-focus-toggle.t
277 --------------------------------------------
278
279 == Anatomy of a testcase
280
281 Learning by example is definitely a good strategy when you are wondering how to
282 write a testcase. Let's take +t/11-goto.t+ as an easy example and go through it
283 step by step:
284
285 .t/11-goto.t: Boilerplate
286 ----------------------
287 #!perl
288 # vim:ts=4:sw=4:expandtab
289
290 use i3test;
291 use File::Temp;
292
293 my $x = X11::XCB::Connection->new;
294 -----------------------
295
296 This is what we call boilerplate. It exists at the top of every test file (to
297 some extent). The first line is the shebang, which specifies that this file is
298 a Perl script. The second line contains VIM specific settings on how to
299 edit/format this file (use spaces instead of tabs, indent using 4 spaces).
300 Afterwards, the +i3test+ module is used. This module contains i3 testsuite
301 specific functions which you are strongly encouraged to use. They make writing
302 testcases a lot easier and will make it easier for other people to read your
303 tests.
304
305 The next line uses the +File::Temp+ module. This is specific to this testcase,
306 because it needs to generate a temporary name during the test. Many testcases
307 use only the +i3test+ module.
308
309 The last line opens a connection to X11. You might or might not need this in
310 your testcase, depending on whether you are going to open windows (etc.) or
311 only use i3 commands.
312
313 .t/11-goto.t: Setup
314 ----------------------
315 my $tmp = fresh_workspace;
316
317 cmd 'split h';
318 ----------------------
319
320 The first line calls i3test's +fresh_workspace+ function which looks for a
321 currently unused workspace, switches to it, and returns its name. The variable
322 +$tmp+ will end up having a value such as +"/tmp/87kBVcHbA9"+. Note that this
323 is not (necessarily) a valid path, it's just a random workspace name.
324
325 So, now that we are on a new workspace, we ensure that the workspace uses
326 horizontal orientation by issuing the +split h+ command (see the i3 User's
327 Guide for a list of commands). This is not strictly necessary, but good style.
328 In general, the +cmd+ function executes the specified i3 command by using the
329 IPC interface and returns once i3 acknowledged the command.
330
331 .t/11-goto.t: Setup
332 ----------------------
333 #####################################################################
334 # Create two windows and make sure focus switching works
335 #####################################################################
336
337 my $top = open_window($x);
338 my $mid = open_window($x);
339 my $bottom = open_window($x);
340 ----------------------
341
342 In every major section of a testcase, you should put a comment like the one
343 above. This makes it immediately clear how the file is structured.
344
345 The +open_window+ function opens a standard window, which will then be put into
346 tiling mode by i3. If you want a floating window, use the
347 +open_floating_window+ function. These functions accept the same parameters as
348 +X11::XCB::Window->new+, see the i3test documentation at TODO.
349
350 .t/11-goto.t: Helper function
351 ----------------------
352 #
353 # Returns the input focus after sending the given command to i3 via IPC
354 # and syncing with i3
355 #
356 sub focus_after {
357     my $msg = shift;
358
359     cmd $msg;
360     sync_with_i3 $x;
361     return $x->input_focus;
362 }
363 ----------------------
364
365 This section defines a helper function which will be used over and over in this
366 testcase. If you have code which gets executed more than once or twice
367 (depending on the length of your test, use your best judgement), please put it
368 in a function. Tests should be short, concise and clear.
369
370 The +focus_after+ function executes a command and returns the X11 focus after
371 the command was executed. The +sync_with_i3+ command makes sure that i3 could
372 push its state to X11. See <<i3_sync>> to learn how this works exactly.
373
374 .t/11-goto.t: Test assumptions
375 ----------------------
376 $focus = $x->input_focus;
377 is($focus, $bottom->id, "Latest window focused");
378
379 $focus = focus_after('focus left');
380 is($focus, $mid->id, "Middle window focused");
381 ----------------------
382
383 Now, we run the first two real tests. They use +Test::More+'s +is+ function,
384 which compares two values and prints the differences if they are not the same.
385 After the arguments, we supply a short comment to indicate what we are testing
386 here. This makes it vastly more easy for the developer to spot which testcase
387 is the problem in case one fails.
388
389 The first test checks that the most recently opened window is focused.
390 Afterwards, the command +focus left+ is issued and it is verified that the
391 middle window now has focus.
392
393 Note that this is not a comprehensive test of the +focus+ command -- we would
394 have to test wrapping, focus when using a more complex layout, focusing the
395 parent/child containers, etc. But that is not the point of this testcase.
396 Instead, we just want to know if +$x->input_focus+ corresponds with what we are
397 expecting. If not, something is completely wrong with the test environment and
398 this trivial test will fail.
399
400 .t/11-goto.t: Test that the feature does not work (yet)
401 ----------------------
402 #####################################################################
403 # Now goto a mark which does not exist
404 #####################################################################
405
406 my $random_mark = mktemp('mark.XXXXXX');
407
408 $focus = focus_after(qq|[con_mark="$random_mark"] focus|);
409 is($focus, $mid->id, "focus unchanged");
410 ----------------------
411
412 Syntax hint: The qq keyword is the interpolating quote operator. It lets you
413 chose a quote character (in this case the +|+ character, a pipe). This makes
414 having double quotes in our string easy.
415
416 In this new major section, a random mark (mark is an identifier for a window,
417 see "VIM-like marks" in the i3 User’s Guide) will be generated. Afterwards, we
418 test that trying to focus that mark will not do anything. This is important: Do
419 not only test that using a feature has the expected outcome, but also test that
420 using it without properly initializing it does no harm. This command could for
421 example have changed focus anyways (a bug) or crash i3 (obviously a bug).
422
423 .t/11-goto.t: Test that the feature does work
424 ----------------------
425 cmd "mark $random_mark";
426
427 $focus = focus_after('focus left');
428 is($focus, $top->id, "Top window focused");
429
430 $focus = focus_after(qq|[con_mark="$random_mark"] focus|);
431 is($focus, $mid->id, "goto worked");
432 ----------------------
433
434 Remember: Focus was on the middle window (we verified that earlier in "Test
435 assumptions"). We now mark the middle window with our randomly generated mark.
436 Afterwards, we switch focus away from the middle window to be able to tell if
437 focusing it via its mark will work. If the test works, the goto command seems
438 to be working.
439
440 .t/11-goto.t: Test corner case
441 ----------------------
442 # check that we can specify multiple criteria
443
444 $focus = focus_after('focus left');
445 is($focus, $top->id, "Top window focused");
446
447 $focus = focus_after(qq|[con_mark="$random_mark" con_mark="$random_mark"] focus|);
448 is($focus, $mid->id, "goto worked");
449 ----------------------
450
451 Now we test the same feature, but specifying the mark twice in the command.
452 This should have no effect, but let’s be sure: test it and see if things go
453 wrong.
454
455 .t/11-goto.t: Test second code path
456 ----------------------
457 #####################################################################
458 # Check whether the focus command will switch to a different
459 # workspace if necessary
460 #####################################################################
461
462 my $tmp2 = fresh_workspace;
463
464 is(focused_ws(), $tmp2, 'tmp2 now focused');
465
466 cmd qq|[con_mark="$random_mark"] focus|;
467
468 is(focused_ws(), $tmp, 'tmp now focused');
469 ----------------------
470
471 This part of the test checks that focusing windows by mark works across
472 workspaces. It uses i3test's +focused_ws+ function to get the current
473 workspace.
474
475 .t/11-goto.t: Test second code path
476 ----------------------
477 done_testing;
478 ----------------------
479
480 The end of every testcase has to contain the +done_testing+ line. This tells
481 +complete-run.pl+ that the test was finished successfully. If it does not
482 occur, the test might have crashed during execution -- some of the reasons why
483 that could happen are bugs in the used modules, bugs in the testcase itself or
484 an i3 crash resulting in the testcase being unable to communicate with i3 via
485 IPC anymore.
486
487 [[i3_sync]]
488 == Appendix A: The i3 sync protocol
489
490 Consider the following situation: You open two windows in your testcase, then
491 you use +focus left+ and want to verify that the X11 focus has been updated
492 properly. Sounds simple, right? Let’s assume you use this straight-forward
493 implementation:
494
495 .Racey focus testcase
496 -----------
497 my $left = open_window($x);
498 my $right = open_window($x);
499 cmd 'focus left';
500 is($x->input_focus, $left->id, 'left window focused');
501 ----------
502
503 However, the test fails. Sometimes. Apparently, there is a race condition in
504 your test. If you think about it, this is because you are using two different
505 pieces of software: You tell i3 to update focus, i3 confirms that, and then you
506 ask X11 to give you the current focus. There is a certain time i3 needs to
507 update the X11 state. If the testcase gets CPU time before X11 processed i3's
508 requests, the test will fail.
509
510 image::i3-sync.png["Diagram of the race condition", title="Diagram of the race condition"]
511
512 One way to "solve" this would be to add +sleep 0.5;+ after the +cmd+ call.
513 After 0.5 seconds it should be safe to assume that focus has been updated,
514 right?
515
516 In practice, this usually works. However, it has several problems:
517
518 1. This is obviously not a clean solution, but a workaround. Ugly.
519 2. On very slow machines, this might not work. Unlikely, but in different
520    situations (a delay to wait for i3 to startup) the necessary time is much
521    harder to guess, even for fast machines.
522 3. This *wastes a lot of time*. Usually, your computer is much faster than 0.5s
523    to update the status. However, sometimes, it might take 0.4s, so we can’t
524    make it +sleep 0.1+.
525
526 To illustrate how grave the problem with wasting time actually is: Before
527 removing all sleeps from the testsuite, a typical run using 4 separate X
528 servers took around 50 seconds on my machine. After removing all the sleeps,
529 we achieved times of about 25 seconds. This is very significant and influences
530 the way you think about tests -- the faster they are, the more likely you are
531 to check whether everything still works quite often (which you should).
532
533 What I am trying to say is: Delays adds up quickly and make the test suite
534 less robust.
535
536 The real solution for this problem is a mechanism which I call "the i3 sync
537 protocol". The idea is to send a request (which does not modify state) via X11
538 to i3 which will then be answered. Due to the request's position in the event
539 queue (*after* all previous events), you can be sure that by the time you
540 receive the reply, all other events have been dealt with by i3 (and, more
541 importantly, X11).
542
543 image::i3-sync-working.png["Diagram of the i3 sync solution", title="Diagram of the i3 sync solution"]
544
545 === Implementation details
546
547 The client which wants to sync with i3 initiates the protocol by sending a
548 ClientMessage to the X11 root window:
549
550 .Send ClientMessage
551 -------------------
552 # Generate a ClientMessage, see xcb_client_message_t
553 my $msg = pack "CCSLLLLLLL",
554     CLIENT_MESSAGE, # response_type
555     32,     # format
556     0,      # sequence
557     $root,  # destination window
558     $x->atom(name => 'I3_SYNC')->id,
559
560     $_sync_window->id,    # data[0]: our own window id
561     $myrnd, # data[1]: a random value to identify the request
562     0,
563     0,
564     0;
565
566 # Send it to the root window -- since i3 uses the SubstructureRedirect
567 # event mask, it will get the ClientMessage.
568 $x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);
569 -------------------
570
571 i3 will then reply with the same ClientMessage, sent to the window specified in
572 +data[0]+. In the reply, +data[0]+ and +data[1]+ are exactly the same as in the
573 request. You should use a random value in +data[1]+ and check that you received
574 the same one when getting the reply.
575
576 == Appendix B: Socket activation
577
578 Socket activation is a mechanism which was made popular by systemd, an init
579 replacement. It basically describes creating a listening socket before starting
580 a program.  systemd will invoke the program only when an actual connection to
581 the socket is made, hence the term socket activation.
582
583 The interesting part of this (in the i3 context) is that you can very precisely
584 detect when the program is ready (finished its initialization).
585
586 === Preparing the listening socket
587
588 +complete-run.pl+ will create a listening UNIX socket which it will then pass
589 to i3. This socket will be used by i3 as an additional IPC socket, just like
590 the one it will create on its own. Passing the socket happens implicitly
591 because children will inherit the parent’s sockets when fork()ing and sockets
592 will continue to exist after an exec() call (unless CLOEXEC is set of course).
593
594 The only explicit things +complete-run.pl+ has to do is setting the +LISTEN_FDS+
595 environment variable to the number of sockets which exist (1 in our case) and
596 setting the +LISTEN_PID+ environment variable to the current process ID. Both
597 variables are necessary so that the program (i3) knows how many sockets it
598 should use and if the environment variable is actually intended for it. i3 will
599 then start looking for sockets at file descriptor 3 (since 0, 1 and 2 are used
600 for stdin, stdout and stderr, respectively).
601
602 The actual Perl code which sets up the socket, fork()s, makes sure the socket
603 has file descriptor 3 and sets up the environment variables follows (shortened
604 a bit):
605
606
607 .Setup socket and environment
608 -----------------------------
609 my $socket = IO::Socket::UNIX->new(
610     Listen => 1,
611     Local => $args{unix_socket_path},
612 );
613
614 my $pid = fork;
615 if ($pid == 0) {
616     $ENV{LISTEN_PID} = $$;
617     $ENV{LISTEN_FDS} = 1;
618
619     # Only pass file descriptors 0 (stdin), 1 (stdout),
620     # 2 (stderr) and 3 (socket) to the child.
621     $^F = 3;
622
623     # If the socket does not use file descriptor 3 by chance
624     # already, we close fd 3 and dup2() the socket to 3.
625     if (fileno($socket) != 3) {
626         POSIX::close(3);
627         POSIX::dup2(fileno($socket), 3);
628     }
629
630     exec "/usr/bin/i3";
631 }
632 -----------------------------
633
634 === Waiting for a reply
635
636 In the parent process, we want to know when i3 is ready to answer our IPC
637 requests and handle our windows. Therefore, after forking, we immediately close
638 the listening socket (i3 will handle this side of the socket) and connect to it
639 (remember, we are talking about a named UNIX socket) as a client. This connect
640 call will immediately succeed because the kernel buffers it. Then, we send a
641 request (of type GET_TREE, but that is not really relevant). Writing data to
642 the socket will also succeed immediately because, again, the kernel buffers it
643 (only up to a certain amount of data of course).
644
645 Afterwards, we just blockingly wait until we get an answer. In the child
646 process, i3 will setup the listening socket in its event loop. Immediately
647 after actually starting the event loop, it will notice a new client connecting
648 (the parent process) and handle its request. Since all initialization has been
649 completed successfully by the time the event loop is entered, we can now assume
650 that i3 is ready.
651
652 === Timing and conclusion
653
654 A beautiful feature of this mechanism is that it does not depend on timing. It
655 does not matter when the child process gets CPU time or when the parent process
656 gets CPU time. On heavily loaded machines (or machines with multiple CPUs,
657 cores or unreliable schedulers), this makes waiting for i3 much more robust.
658
659 Before using socket activation, we typically used a +sleep(1)+ and hoped that
660 i3 was initialized by that time. Of course, this breaks on some (slow)
661 computers and wastes a lot of time on faster computers. By using socket
662 activation, we decreased the total amount of time necessary to run all tests
663 (72 files at the time of writing) from > 100 seconds to 16 seconds. This makes
664 it significantly more attractive to run the test suite more often (or at all)
665 during development.
666
667 An alternative approach to using socket activation is polling for the existence
668 of the IPC socket and connecting to it. While this might be slightly easier to
669 implement, it wastes CPU time and is considerably uglier than this solution
670 :). After all, +lib/SocketActivation.pm+ contains only 54 SLOC.