MySQL 8.2.0
Source Code Documentation
psi_file_bits.h
Go to the documentation of this file.
1/* Copyright (c) 2008, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef COMPONENTS_SERVICES_BITS_PSI_FILE_BITS_H
24#define COMPONENTS_SERVICES_BITS_PSI_FILE_BITS_H
25
26#ifndef MYSQL_ABI_CHECK
27#include <stddef.h> /* size_t */
28#endif
29
32
33/**
34 @file mysql/components/services/bits/psi_file_bits.h
35 Performance schema instrumentation interface.
36
37 @defgroup psi_abi_file File Instrumentation (ABI)
38 @ingroup psi_abi
39 @{
40*/
41
42/**
43 Instrumented file key.
44 To instrument a file, a file key must be obtained using @c register_file.
45 Using a zero key always disable the instrumentation.
46*/
47typedef unsigned int PSI_file_key;
48
49/**
50 Interface for an instrumented file handle.
51 This is an opaque structure.
52*/
53struct PSI_file;
54typedef struct PSI_file PSI_file;
55
56/**
57 Interface for an instrumented file operation.
58 This is an opaque structure.
59*/
60struct PSI_file_locker;
62
63/** Operation performed on an instrumented file. */
65 /** File creation, as in @c create(). */
67 /** Temporary file creation, as in @c create_temp_file(). */
69 /** File open, as in @c open(). */
71 /** File open, as in @c fopen(). */
73 /** File close, as in @c close(). */
75 /** File close, as in @c fclose(). */
77 /**
78 Generic file read, such as @c fgets(), @c fgetc(), @c fread(), @c read(),
79 @c pread().
80 */
82 /**
83 Generic file write, such as @c fputs(), @c fputc(), @c fprintf(),
84 @c vfprintf(), @c fwrite(), @c write(), @c pwrite().
85 */
87 /** Generic file seek, such as @c fseek() or @c seek(). */
89 /** Generic file tell, such as @c ftell() or @c tell(). */
91 /** File flush, as in @c fflush(). */
93 /** File stat, as in @c stat(). */
95 /** File stat, as in @c fstat(). */
97 /** File chsize, as in @c my_chsize(). */
99 /** File delete, such as @c my_delete() or @c my_delete_with_symlink(). */
101 /** File rename, such as @c my_rename() or @c my_rename_with_symlink(). */
103 /** File sync, as in @c fsync() or @c my_sync(). */
104 PSI_FILE_SYNC = 16
107
108/**
109 File instrument information.
110 @since PSI_FILE_VERSION_1
111 This structure is used to register an instrumented file.
112*/
114 /**
115 Pointer to the key assigned to the registered file.
116 */
118 /**
119 The name of the file instrument to register.
120 */
121 const char *m_name;
122 /**
123 The flags of the file instrument to register.
124 @sa PSI_FLAG_SINGLETON
125 */
126 unsigned int m_flags;
127 /** Volatility index. */
129 /** Documentation. */
130 const char *m_documentation;
131};
133
134/**
135 State data storage for @c get_thread_file_name_locker_v1_t.
136 This structure provide temporary storage to a file locker.
137 The content of this structure is considered opaque,
138 the fields are only hints of what an implementation
139 of the psi interface can use.
140 This memory is provided by the instrumented code for performance reasons.
141 @sa get_thread_file_name_locker_v1_t
142 @sa get_thread_file_stream_locker_v1_t
143 @sa get_thread_file_descriptor_locker_v1_t
144*/
146 /** Internal state. */
147 unsigned int m_flags;
148 /** Current operation. */
150 /** Current file. */
152 /** Current file name. */
153 const char *m_name;
154 /** Current file class. */
155 void *m_class;
156 /** Current thread. */
158 /** Operation number of bytes. */
160 /** Timer start. */
161 unsigned long long m_timer_start{0ULL};
162 /** Timer function. */
163 unsigned long long (*m_timer)(void);
164 /** Internal data. */
165 void *m_wait{nullptr};
166};
168
169/**
170 File registration API.
171 @param category a category name (typically a plugin name)
172 @param info an array of file info to register
173 @param count the size of the info array
174*/
175typedef void (*register_file_v1_t)(const char *category,
176 struct PSI_file_info_v1 *info, int count);
177
178/**
179 Create a file instrumentation for a created file.
180 This method does not create the file itself, but is used to notify the
181 instrumentation interface that a file was just created.
182 @param key the file instrumentation key for this file
183 @param name the file name
184 @param file the file handle
185*/
186typedef void (*create_file_v1_t)(PSI_file_key key, const char *name, File file);
187
188/**
189 Get a file instrumentation locker, for opening or creating a file.
190 @param state data storage for the locker
191 @param key the file instrumentation key
192 @param op the operation to perform
193 @param name the file name
194 @param identity a pointer representative of this file.
195 @return a file locker, or NULL
196*/
197typedef struct PSI_file_locker *(*get_thread_file_name_locker_v1_t)(
199 enum PSI_file_operation op, const char *name, const void *identity);
200
201/**
202 Get a file stream instrumentation locker.
203 @param state data storage for the locker
204 @param file the file stream to access
205 @param op the operation to perform
206 @return a file locker, or NULL
207*/
208typedef struct PSI_file_locker *(*get_thread_file_stream_locker_v1_t)(
209 struct PSI_file_locker_state_v1 *state, struct PSI_file *file,
210 enum PSI_file_operation op);
211
212/**
213 Get a file instrumentation locker.
214 @param state data storage for the locker
215 @param file the file descriptor to access
216 @param op the operation to perform
217 @return a file locker, or NULL
218*/
219typedef struct PSI_file_locker *(*get_thread_file_descriptor_locker_v1_t)(
220 struct PSI_file_locker_state_v1 *state, File file,
221 enum PSI_file_operation op);
222
223/**
224 Start a file instrumentation open operation.
225 @param locker the file locker
226 @param src_file the source file name
227 @param src_line the source line number
228*/
229typedef void (*start_file_open_wait_v1_t)(struct PSI_file_locker *locker,
230 const char *src_file,
231 unsigned int src_line);
232
233/**
234 End a file instrumentation open operation, for file streams.
235 @param locker the file locker.
236 @param result the opened file (NULL indicates failure, non NULL success).
237 @return an instrumented file handle
238*/
239typedef struct PSI_file *(*end_file_open_wait_v1_t)(
240 struct PSI_file_locker *locker, void *result);
241
242/**
243 End a file instrumentation open operation, for non stream files.
244 @param locker the file locker.
245 @param file the file number assigned by open() or create() for this file.
246*/
248 struct PSI_file_locker *locker, File file);
249
250/**
251 End a file instrumentation open operation, for non stream temporary files.
252 @param locker the file locker.
253 @param file the file number assigned by open() or create() for this file.
254 @param filename the file name generated during temporary file creation.
255*/
257 struct PSI_file_locker *locker, File file, const char *filename);
258
259/**
260 Record a file instrumentation start event.
261 @param locker a file locker for the running thread
262 @param count the number of bytes requested, or 0 if not applicable
263 @param src_file the source file name
264 @param src_line the source line number
265*/
266typedef void (*start_file_wait_v1_t)(struct PSI_file_locker *locker,
267 size_t count, const char *src_file,
268 unsigned int src_line);
269
270/**
271 Record a file instrumentation end event.
272 Note that for file close operations, the instrumented file handle
273 associated with the file (which was provided to obtain a locker)
274 is invalid after this call.
275 @param locker a file locker for the running thread
276 @param count the number of bytes actually used in the operation,
277 or 0 if not applicable, or -1 if the operation failed
278 @sa get_thread_file_name_locker
279 @sa get_thread_file_stream_locker
280 @sa get_thread_file_descriptor_locker
281*/
282typedef void (*end_file_wait_v1_t)(struct PSI_file_locker *locker,
283 size_t count);
284
285/**
286 Start a file instrumentation close operation.
287 @param locker the file locker
288 @param src_file the source file name
289 @param src_line the source line number
290*/
291typedef void (*start_file_close_wait_v1_t)(struct PSI_file_locker *locker,
292 const char *src_file,
293 unsigned int src_line);
294
295/**
296 End a file instrumentation close operation.
297 @param locker the file locker.
298 @param rc the close operation return code (0 for success).
299*/
300typedef void (*end_file_close_wait_v1_t)(struct PSI_file_locker *locker,
301 int rc);
302
303/**
304 Record a file instrumentation start event.
305 @param locker a file locker for the running thread
306 @param count the number of bytes requested, or 0 if not applicable
307 @param old_name name of the file to be renamed.
308 @param new_name name of the file after rename.
309 @param src_file the source file name
310 @param src_line the source line number
311*/
312typedef void (*start_file_rename_wait_v1_t)(struct PSI_file_locker *locker,
313 size_t count, const char *old_name,
314 const char *new_name,
315 const char *src_file,
316 unsigned int src_line);
317/**
318 Rename a file instrumentation close operation.
319 @param locker the file locker.
320 @param old_name name of the file to be renamed.
321 @param new_name name of the file after rename.
322 @param rc the rename operation return code (0 for success).
323*/
324typedef void (*end_file_rename_wait_v1_t)(struct PSI_file_locker *locker,
325 const char *old_name,
326 const char *new_name, int rc);
327
330
331/** @} (end of group psi_abi_file) */
332
333#endif /* COMPONENTS_SERVICES_BITS_PSI_FILE_BITS_H */
struct PSI_file PSI_file
Definition: psi_file_bits.h:54
void(* start_file_rename_wait_v1_t)(struct PSI_file_locker *locker, size_t count, const char *old_name, const char *new_name, const char *src_file, unsigned int src_line)
Record a file instrumentation start event.
Definition: psi_file_bits.h:312
void(* end_file_rename_wait_v1_t)(struct PSI_file_locker *locker, const char *old_name, const char *new_name, int rc)
Rename a file instrumentation close operation.
Definition: psi_file_bits.h:324
void(* end_file_wait_v1_t)(struct PSI_file_locker *locker, size_t count)
Record a file instrumentation end event.
Definition: psi_file_bits.h:282
void(* start_file_wait_v1_t)(struct PSI_file_locker *locker, size_t count, const char *src_file, unsigned int src_line)
Record a file instrumentation start event.
Definition: psi_file_bits.h:266
void(* end_file_open_wait_and_bind_to_descriptor_v1_t)(struct PSI_file_locker *locker, File file)
End a file instrumentation open operation, for non stream files.
Definition: psi_file_bits.h:247
void(* start_file_close_wait_v1_t)(struct PSI_file_locker *locker, const char *src_file, unsigned int src_line)
Start a file instrumentation close operation.
Definition: psi_file_bits.h:291
unsigned int PSI_file_key
Instrumented file key.
Definition: psi_file_bits.h:47
void(* end_temp_file_open_wait_and_bind_to_descriptor_v1_t)(struct PSI_file_locker *locker, File file, const char *filename)
End a file instrumentation open operation, for non stream temporary files.
Definition: psi_file_bits.h:256
void(* create_file_v1_t)(PSI_file_key key, const char *name, File file)
Create a file instrumentation for a created file.
Definition: psi_file_bits.h:186
void(* register_file_v1_t)(const char *category, struct PSI_file_info_v1 *info, int count)
File registration API.
Definition: psi_file_bits.h:175
void(* end_file_close_wait_v1_t)(struct PSI_file_locker *locker, int rc)
End a file instrumentation close operation.
Definition: psi_file_bits.h:300
struct PSI_file_locker PSI_file_locker
Definition: psi_file_bits.h:61
void(* start_file_open_wait_v1_t)(struct PSI_file_locker *locker, const char *src_file, unsigned int src_line)
Start a file instrumentation open operation.
Definition: psi_file_bits.h:229
PSI_file_operation
Operation performed on an instrumented file.
Definition: psi_file_bits.h:64
@ PSI_FILE_OPEN
File open, as in open().
Definition: psi_file_bits.h:70
@ PSI_FILE_STREAM_CLOSE
File close, as in fclose().
Definition: psi_file_bits.h:76
@ PSI_FILE_WRITE
Generic file write, such as fputs(), fputc(), fprintf(), vfprintf(), fwrite(), write(),...
Definition: psi_file_bits.h:86
@ PSI_FILE_CHSIZE
File chsize, as in my_chsize().
Definition: psi_file_bits.h:98
@ PSI_FILE_CLOSE
File close, as in close().
Definition: psi_file_bits.h:74
@ PSI_FILE_SEEK
Generic file seek, such as fseek() or seek().
Definition: psi_file_bits.h:88
@ PSI_FILE_TELL
Generic file tell, such as ftell() or tell().
Definition: psi_file_bits.h:90
@ PSI_FILE_STREAM_OPEN
File open, as in fopen().
Definition: psi_file_bits.h:72
@ PSI_FILE_CREATE
File creation, as in create().
Definition: psi_file_bits.h:66
@ PSI_FILE_FSTAT
File stat, as in fstat().
Definition: psi_file_bits.h:96
@ PSI_FILE_RENAME
File rename, such as my_rename() or my_rename_with_symlink().
Definition: psi_file_bits.h:102
@ PSI_FILE_STAT
File stat, as in stat().
Definition: psi_file_bits.h:94
@ PSI_FILE_DELETE
File delete, such as my_delete() or my_delete_with_symlink().
Definition: psi_file_bits.h:100
@ PSI_FILE_FLUSH
File flush, as in fflush().
Definition: psi_file_bits.h:92
@ PSI_FILE_CREATE_TMP
Temporary file creation, as in create_temp_file().
Definition: psi_file_bits.h:68
@ PSI_FILE_READ
Generic file read, such as fgets(), fgetc(), fread(), read(), pread().
Definition: psi_file_bits.h:81
@ PSI_FILE_SYNC
File sync, as in fsync() or my_sync().
Definition: psi_file_bits.h:104
struct PSI_thread PSI_thread
Definition: psi_thread_bits.h:81
Types to make file and socket I/O compatible.
int File
Definition: my_io_bits.h:50
static int count
Definition: myisam_ftdump.cc:44
Log info(cout, "NOTE")
Definition: os0file.h:88
static const char * category
Definition: sha2_password.cc:169
const char * filename
Definition: pfs_example_component_population.cc:66
struct result result
Definition: result.h:33
Performance schema instrumentation interface.
required string key
Definition: replication_asynchronous_connection_failover.proto:59
case opt name
Definition: sslopt-case.h:32
File instrument information.
Definition: psi_file_bits.h:113
const char * m_name
The name of the file instrument to register.
Definition: psi_file_bits.h:121
int m_volatility
Volatility index.
Definition: psi_file_bits.h:128
const char * m_documentation
Documentation.
Definition: psi_file_bits.h:130
unsigned int m_flags
The flags of the file instrument to register.
Definition: psi_file_bits.h:126
PSI_file_key * m_key
Pointer to the key assigned to the registered file.
Definition: psi_file_bits.h:117
State data storage for get_thread_file_name_locker_v1_t.
Definition: psi_file_bits.h:145
struct PSI_file * m_file
Current file.
Definition: psi_file_bits.h:151
size_t m_number_of_bytes
Operation number of bytes.
Definition: psi_file_bits.h:159
const char * m_name
Current file name.
Definition: psi_file_bits.h:153
unsigned long long(* m_timer)(void)
Timer function.
Definition: psi_file_bits.h:163
struct PSI_thread * m_thread
Current thread.
Definition: psi_file_bits.h:157
enum PSI_file_operation m_operation
Current operation.
Definition: psi_file_bits.h:149
unsigned long long m_timer_start
Timer start.
Definition: psi_file_bits.h:161
void * m_class
Current file class.
Definition: psi_file_bits.h:155
void * m_wait
Internal data.
Definition: psi_file_bits.h:165
unsigned int m_flags
Internal state.
Definition: psi_file_bits.h:147