Mercurial > molko
annotate libmlk-core/mlk/core/trace.h @ 564:e91f37da2992
core: doxygenize window
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 08 Mar 2023 20:09:21 +0100 |
parents | 970cad994a95 |
children |
rev | line source |
---|---|
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 /* |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 * trace.h -- non-fatal message logs |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 * |
445
773a082f0b91
misc: update copyright years
David Demelier <markand@malikania.fr>
parents:
431
diff
changeset
|
4 * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr> |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 * |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 * Permission to use, copy, modify, and/or distribute this software for any |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 * purpose with or without fee is hereby granted, provided that the above |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 * copyright notice and this permission notice appear in all copies. |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 * |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 */ |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
320
diff
changeset
|
19 #ifndef MLK_CORE_TRACE_H |
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
320
diff
changeset
|
20 #define MLK_CORE_TRACE_H |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
22 /** |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
23 * \file mlk/core/trace.h |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
24 * \brief Non-fatal message logs |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
25 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
26 * This module provides a simple way to log messages from the API or user code, |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
27 * mostly when non-fatal errors happened. |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
28 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
29 * The default implementation uses printf with a timestamp in the form hh:mm::s |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
30 * to the standard output, it can be disabled using your own |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
31 * ::mlk_trace_handler or setting it to NULL. |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
32 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
33 * Example of lines generated by default: |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
34 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
35 * ``` |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
36 * 10:20:30: hello world |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
37 * 20:50:00: goodbye world |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
38 * ``` |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
39 */ |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
40 |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 #include <stdarg.h> |
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
43 /** |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
44 * Maximum trace line |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
45 */ |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
46 #define MLK_TRACE_LINE_MAX (128) |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
48 /** |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
49 * Default trace handler implementation |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
50 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
51 * Can be set to NULL to disable logging. |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
52 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
53 * \param line the line to print |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
54 */ |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
55 extern void (*mlk_trace_handler)(const char *line); |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 |
517
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
57 #if defined(__cplusplus) |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
58 extern "C" { |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
59 #endif |
292
08ab73b32832
misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
60 |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
61 /** |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
62 * Write a trace log using a [printf] format style. |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
63 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
64 * [printf]: https://en.cppreference.com/w/c/io/fprintf |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
65 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
66 * \pre fmt != NULL |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
67 * \param fmt the printf format string |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
68 */ |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 void |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
70 mlk_tracef(const char *fmt, ...); |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
72 /** |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
73 * Similar to ::mlk_tracef but using a `va_list` instead. |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
74 * |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
75 * \pre fmt != NULL |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
76 * \param fmt the printf format string |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
77 * \param ap the variadic handle |
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
78 */ |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
79 void |
541
970cad994a95
core: doxygenize trace
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
80 mlk_traceva(const char *fmt, va_list ap); |
141
4eeeccf2b732
core: add trace/vtrace functions, closes #2493
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
81 |
517
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
82 #if defined(__cplusplus) |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
83 } |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
473
diff
changeset
|
84 #endif |
292
08ab73b32832
misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
85 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
320
diff
changeset
|
86 #endif /* !MLK_CORE_TRACE_H */ |