1 2 3 4 5 6 7 8 9 10 11 12
13 /*!
14 * ======== ILogger ========
15 * Interface to service Log events
16 *
17 * A logger is responsible for recording, transmitting, or otherwise
18 * handling `{@link Log#EventDesc Log Events}` generated by clients of the
19 * `{@link Log}` module. The `Log` module uses modules that implement the
20 * `ILogger` interface to record the log events. Most application code will
21 * use the `Log` module instead of directly calling the specific `ILogger`
22 * module implementation.
23 *
24 * All logger implementations must inherit from this interface. The
25 * derived implementations must implement the functions defined in this
26 * interface but may also add additional configuration parameters and
27 * functions.
28 */
29 interface ILogger {
30
31 instance:
32
33 /*!
34 * ======== write4 ========
35 * Process a log event with up to 4 arguments.
36 *
37 * At the time this method is called, `evt` encodes two values: the
38 * module ID of the module that "triggered" a `{@link Log#Event}`
39 * and the `{@link Log#EventId}` of the event. The module ID can
40 * be obtained via `{@link Types#getModuleId}(evt)`
41 * and the event ID can be obtained via
42 * `{@link Types#getEventId}(evt)`.
43 *
44 * The event ID can be used to compare against other known
45 * `Log.Event`s.
46 * @p(code)
47 * if (Log_getEventId(MY_EVENT) == Types_getEventId(evt)) {
48 * :
49 * }
50 * @p
51 *
52 * The event ID value of `0` is used to indicate an event triggered
53 * by a call to one of the `{@link Log#print0 Log_print[0-6]}`
54 * methods. These methods take a
55 * format string rather than a `Log_Event` argument and, as a result,
56 * the event ID encoded in `evt` is `0` and the parameter `a1` is
57 * the format string.
58 *
59 * Non-zero event IDs can also be used to access the `msg` string
60 * associated with the `{@link Log#EventDesc}` that originally
61 * defined the `Log` event.
62 * @p(code)
63 * Types_EventId id = Types_getEventId(evt));
64 * if (id != 0) {
65 * String msg = Text_ropeText(id);
66 * System_aprintf(msg, a1, a2, a3, a4);
67 * }
68 * @p
69 * This works because an event's ID is simply an offset into a table
70 * of characters (maintained by the `{@link Text}` module)
71 * containing the event's msg string.
72 *
73 * @param(evt) event to be logged
74 *
75 * @param(a1) arbitrary argument passed by caller
76 *
77 * This parameter, along with `a2`, `a3`, and `a4` are parameters
78 * that are to be interpreted according to the message format string
79 * associated with `evt`.
80 *
81 * @see Log#Event
82 * @see Log#EventDesc
83 * @see Text#ropeText
84 * @see Types#getEventId
85 */
86 Void write4(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
87
88 /*!
89 * ======== write8 ========
90 * Process a log event with up to 8 arguments.
91 *
92 * Same as `write4` except with 8 arguments rather than 4.
93 *
94 * @see ILogger#write4()
95 */
96 Void write8(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
97 IArg a5, IArg a6, IArg a7, IArg a8);
98 }
99 100 101
102