VLC  4.0.0-dev
vlc_tracer.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_tracer.h: tracing interface
3  * This library provides basic functions for threads to interact with user
4  * interface, such as trace output.
5  *****************************************************************************
6  * Copyright (C) 2021 VLC authors and VideoLAN
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22 
23 #ifndef VLC_TRACES_H
24 #define VLC_TRACES_H
25 
26 #include <stdarg.h>
27 
28 /**
29  * \defgroup traces Tracing
30  * \ingroup os
31  * \brief Message traces
32  *
33  * Functions for modules to emit traces.
34  *
35  * @{
36  * \file
37  * Tracing functions
38  */
39 
40 /**
41  * Trace message values
42  */
44 {
47 };
48 
49 typedef union
50 {
51  int64_t integer;
52  const char *string;
54 
55 /**
56  * Trace message
57  */
58 struct vlc_tracer_entry
59 {
60  const char *key; /**< Key to identify the value */
61  vlc_tracer_value_t value; /**< Trace value */
62  enum vlc_tracer_value type; /**< Type of the value */
63 };
64 
65 struct vlc_tracer;
66 
67 /**
68  * Trace logging callback signature.
69  *
70  * va-args can only be \ref vlc_tracer_entry and the va-args list
71  * should be ended by a \ref vlc_tracer_entry with a NULL key.
72  * \param data data pointer as provided to vlc_tracer_Trace().
73  */
74 typedef void (*vlc_trace_cb) (void *data, va_list entries);
75 
77 {
79  void (*destroy)(void *data);
80 };
81 
82 /**
83  * Emit traces
84  *
85  * va-args are a list of key / value parameters.
86  * Key must be a not NULL string.
87  * Value has to be defined with one of the type defined
88  * in the \ref vlc_tracer_entry union.
89  * \param tracer tracer emitting the traces
90  */
91 VLC_API void vlc_tracer_Trace(struct vlc_tracer *tracer, ...);
92 
93 /**
94  * \defgroup tracer Tracer
95  * \brief Tracing back-end.
96  *
97  * @{
98  */
99 
100 static inline struct vlc_tracer_entry vlc_tracer_entry_FromTick(const char *key, vlc_tick_t value)
101 {
102  vlc_tracer_value_t tracer_value;
103  tracer_value.integer = value;
104  struct vlc_tracer_entry trace = { key, tracer_value, VLC_TRACER_INT };
105  return trace;
106 }
107 
108 static inline struct vlc_tracer_entry vlc_tracer_entry_FromString(const char *key, const char *value)
109 {
110  vlc_tracer_value_t tracer_value;
111  tracer_value.string = value;
112  struct vlc_tracer_entry trace = { key, tracer_value, VLC_TRACER_STRING };
113  return trace;
114 }
115 
116 #ifndef __cplusplus
117 #define VLC_TRACE_END \
118  vlc_tracer_entry_FromString(NULL, NULL)
119 
120 #define VLC_TRACE(key, value) \
121  _Generic((value), \
122  vlc_tick_t: vlc_tracer_entry_FromTick, \
123  char *: vlc_tracer_entry_FromString, \
124  const char *: vlc_tracer_entry_FromString) (key, value)
125 #else
126 #define VLC_TRACE_END \
127  vlc_tracer_entry_FromString(nullptr, nullptr)
128 
129 static inline struct vlc_tracer_entry VLC_TRACE(const char *key, vlc_tick_t value)
130 {
132 }
133 
134 static inline struct vlc_tracer_entry VLC_TRACE(const char *key, char *value)
135 {
137 }
138 
139 static inline struct vlc_tracer_entry VLC_TRACE(const char *key, const char *value)
140 {
142 }
143 #endif
144 
145 /*
146  * Helper trace functions
147  */
148 
149 static inline void vlc_tracer_TraceStreamPTS(struct vlc_tracer *tracer, const char *type,
150  const char *id, const char* stream,
151  vlc_tick_t pts)
152 {
153  vlc_tracer_Trace(tracer, VLC_TRACE("type", type), VLC_TRACE("id", id),
154  VLC_TRACE("stream", stream), VLC_TRACE("pts", NS_FROM_VLC_TICK(pts)),
155  VLC_TRACE_END);
156 }
157 
158 static inline void vlc_tracer_TraceStreamDTS(struct vlc_tracer *tracer, const char *type,
159  const char *id, const char* stream,
160  vlc_tick_t pts, vlc_tick_t dts)
161 {
162  vlc_tracer_Trace(tracer, VLC_TRACE("type", type), VLC_TRACE("id", id),
163  VLC_TRACE("stream", stream), VLC_TRACE("pts", NS_FROM_VLC_TICK(pts)),
165 }
166 
167 static inline void vlc_tracer_TraceRender(struct vlc_tracer *tracer, const char *type,
168  const char *id, vlc_tick_t pts, vlc_tick_t now)
169 {
170  vlc_tracer_Trace(tracer, VLC_TRACE("type", type), VLC_TRACE("id", id),
171  VLC_TRACE("pts", NS_FROM_VLC_TICK(pts)),
172  VLC_TRACE("render_ts", NS_FROM_VLC_TICK(now)), VLC_TRACE_END);
173 }
174 
175 static inline void vlc_tracer_TracePCR( struct vlc_tracer *tracer, const char *type,
176  const char *id, vlc_tick_t pcr)
177 {
178  vlc_tracer_Trace(tracer, VLC_TRACE("type", type), VLC_TRACE("id", id),
180 }
181 
182 /**
183  * @}
184  */
185 /**
186  * @}
187  */
188 #endif
#define VLC_API
Definition: fourcc_gen.c:31
static void vlc_tracer_TraceStreamPTS(struct vlc_tracer *tracer, const char *type, const char *id, const char *stream, vlc_tick_t pts)
Definition: vlc_tracer.h:150
static void vlc_tracer_TraceRender(struct vlc_tracer *tracer, const char *type, const char *id, vlc_tick_t pts, vlc_tick_t now)
Definition: vlc_tracer.h:168
static struct vlc_tracer_entry vlc_tracer_entry_FromTick(const char *key, vlc_tick_t value)
Definition: vlc_tracer.h:101
#define VLC_TRACE(key, value)
Definition: vlc_tracer.h:121
static void vlc_tracer_TracePCR(struct vlc_tracer *tracer, const char *type, const char *id, vlc_tick_t pcr)
Definition: vlc_tracer.h:176
static void vlc_tracer_TraceStreamDTS(struct vlc_tracer *tracer, const char *type, const char *id, const char *stream, vlc_tick_t pts, vlc_tick_t dts)
Definition: vlc_tracer.h:159
#define VLC_TRACE_END
Definition: vlc_tracer.h:118
static struct vlc_tracer_entry vlc_tracer_entry_FromString(const char *key, const char *value)
Definition: vlc_tracer.h:109
void vlc_tracer_Trace(struct vlc_tracer *tracer,...)
Emit traces.
Definition: tracer.c:49
void(* vlc_trace_cb)(void *data, va_list entries)
Trace logging callback signature.
Definition: vlc_tracer.h:75
vlc_tracer_value
Trace message values.
Definition: vlc_tracer.h:45
@ VLC_TRACER_STRING
Definition: vlc_tracer.h:47
@ VLC_TRACER_INT
Definition: vlc_tracer.h:46
Trace message.
Definition: vlc_tracer.h:60
vlc_tracer_value_t value
Trace value.
Definition: vlc_tracer.h:62
const char * key
Key to identify the value.
Definition: vlc_tracer.h:61
enum vlc_tracer_value type
Type of the value.
Definition: vlc_tracer.h:63
Definition: vlc_tracer.h:78
void(* destroy)(void *data)
Definition: vlc_tracer.h:80
vlc_trace_cb trace
Definition: vlc_tracer.h:79
Definition: tracer.c:36
Definition: vlc_tracer.h:51
const char * string
Definition: vlc_tracer.h:53
int64_t integer
Definition: vlc_tracer.h:52
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
#define NS_FROM_VLC_TICK(vtk)
Definition: vlc_tick.h:155