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