summaryrefslogtreecommitdiff
path: root/src/lib/eina/eina_evlog.h
blob: 82a8dd61384c00360fd24c6d927c9fee630c1702 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
#ifndef EINA_EVLOG_H_
#define EINA_EVLOG_H_

/**
 * @addtogroup Eina_Evlog Event Log Debugging
 * @ingroup Eina
 *
 * @brief These functions are use internally by EFL in general for profiling
 *
 * @{
 *
 * @since 1.15
 */

typedef struct _Eina_Evlog_Item Eina_Evlog_Item;
typedef struct _Eina_Evlog_Buf Eina_Evlog_Buf;

struct _Eina_Evlog_Item
{
   double tim; // the time when this event happened
   double srctim; // if > 0.0, then this is the src event time causing this
   unsigned long long thread; // a thread handle/id where this log happened
   unsigned long long obj; // an object associated with this event (anything)
   unsigned short event_offset; // must be provided - mem pos after item
   unsigned short detail_offset; // if not provided, 0, otherwise mem pos
   unsigned short event_next; // mem offset in bytes for next event;
};

struct _Eina_Evlog_Buf
{
   unsigned char *buf; // current buffer we fill with event logs
   unsigned int size; // the max size of the evlog buffer
   unsigned int top; // the current top byte for a new evlog item
   unsigned int overflow; // how many times this biffer has overflown
   unsigned int stolen; // how many times this buffer has been stolen
};

/**
 * @brief Log an event in our event log for profiling data
 * 
 * Log some interesting event inside of EFL, eg a wakeup (and why etc.).
 * The @p event string must alwasy be provided and be of the form:
 * 
 * "+eventname"
 * "-eventname"
 * "!eventname"
 * 
 * etc. The "+" char means an event is beginning (and any subsequent
 * events logged are really children of this event). The "-" char means an
 * event is ending and so all child events SHOULD have ended by now. A "!"
 * character means the event is a one-off with no beginning or end. Any string
 * following this initial character is the eventy name (and must be provided
 * in the exact same string at both + and - events). This is what will be
 * displayed in a debugger (and may be a well known string thus given a nice
 * UI flourish with icons, labels and colors, so don't change this string
 * unless you want to impact such visibility of these events). The event
 * string after the first character as above can be anything, including white
 * space. It is suggested to keep it human readable and as short as feasible.
 * 
 * The @p object is optional, and if not used, pass in NULL. If it is used,
 * it can be a pointer to anything. It is intended simply to be of use to
 * indicate an event happens on object A vs object B. What this points to
 * is irrelevant as the pointer is never de-references or used other than
 * as a label to differentiate an event on 2 different objects.
 * 
 * The @p srctime parameter is 0.0 if not used, or if used, contains a
 * timepoint for an event that triggered this one. For example, if a device
 * or hardware interrupt causes this event, that device may provide a
 * timestamp/timepoint as part of the device information to indicate the
 * exact time the hardware interrupt happened. This can be useful to have
 * more information as to the latency of an actual source of an event such
 * as the hardware interrupt time, and when the code actually begins seeing
 * or processing it.
 * 
 * The @p detail string is optional (and if unused should be NULL). This is
 * for providing more detailed information to log such as perhaps a the
 * state at the time of the log events or a series of parameters and input
 * that caused this event.
 * 
 * @param event The event string - see above for format
 * @param obj An optional object "pointer" to associate
 * @param srctime An optional source event timestamp that caused this event
 * @param detail An optional event detail string with more info
 * 
 * @since 1.15
 */
EAPI void
eina_evlog(const char *event, void *obj, double srctime, const char *detail);

/**
 * @brief Steal an event log buffer from the evlog core
 * 
 * Only one buffer can be stolen at any time. If you steal a new buffer, the
 * old stolen buffer is "released" back to the evlog core.
 * 
 * @return The stolen evlog buffer
 * 
 * @since 1.15
 */
EAPI Eina_Evlog_Buf *
eina_evlog_steal(void);

/**
 * @brief Begin logging - until now eina_evlog is a NOOP
 */
EAPI void
eina_evlog_start(void);

/**
 * @brief Stop logging
 * 
 * You must not be using any evlog buffers stolen by eina_evlog_steal() by
 * the time you call this function.
 */
EAPI void
eina_evlog_stop(void);

/**
 * @}
 */
#endif