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