Mercurial > molko

annotate libmlk-core/mlk/core/trace.h @ 541:970cad994a95

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: doxygenize trace
author David Demelier <markand@malikania.fr>
date Sun, 05 Mar 2023 13:02:07 +0100
parents 6e8f6640e05b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 */