button.events source code

1 /**
2  * Copyright: Copyright Jason White, 2016
3  * License:   MIT
4  * Authors:   Jason White
5  *
6  * Description:
7  * Classes for receiving events from the build system. This is the general
8  * mechanism through which information is logged.
9  */
10 module button.events;
11 
12 import button.task;
13 import button.state;
14 import core.time : Duration;
15 
16 /**
17  * Interface for handling build system events. This can be used for logging or
18  * visualization purposes.
19  *
20  * Examples of what can be done with this include:
21  *  - Showing build progress in the terminal.
22  *  - Generating a JSON log file to be analyzed later.
23  *  - Sending events to a web interface for visualization.
24  *  - Generating a Gantt chart of task durations to see critical paths.
25  */
26 interface Events
27 {
28     /**
29      * Called when a build has started.
30      */
31     void buildStarted();
32 
33     /**
34      * Called when a build has completed successfully.
35      */
36     void buildSucceeded(Duration duration);
37 
38     /**
39      * Called when a build has failed with the exception that was thrown.
40      */
41     void buildFailed(Duration duration, Exception e);
42 
43     /**
44      * Called when a task has started. Returns a new event handler for tasks.
45      *
46      * Parameters:
47      *   worker = The node on which the task is running. This is guaranteed to
48      *   be between 0 and the size of the task pool.
49      *   task = The task itself.
50      */
51     void taskStarted(size_t worker, const ref Task task);
52 
53     /**
54      * Called when a task has completed successfully.
55      */
56     void taskSucceeded(size_t worker, const ref Task task,
57             Duration duration);
58 
59     /**
60      * Called when a task has failed.
61      */
62     void taskFailed(size_t worker, const ref Task task, Duration duration,
63             const Exception e);
64 
65     /**
66      * Called when a chunk of output is received from the task.
67      */
68     void taskOutput(size_t worker, in ubyte[] chunk);
69 }