MySQL  8.0.27
Source Code Documentation
psi_file_bits.h
Go to the documentation of this file.
1 /* Copyright (c) 2008, 2021, 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_PSI_FILE_BITS_H
24 #define COMPONENTS_SERVICES_PSI_FILE_BITS_H
25 
26 #ifndef MYSQL_ABI_CHECK
27 #include <stddef.h> /* size_t */
28 #endif
29 
31 #include <mysql/components/services/my_io_bits.h> /* File */
32 
33 /**
34  @file
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 */
47 typedef unsigned int PSI_file_key;
48 
49 /**
50  Interface for an instrumented file handle.
51  This is an opaque structure.
52 */
53 struct PSI_file;
54 typedef struct PSI_file PSI_file;
55 
56 /**
57  Interface for an instrumented file operation.
58  This is an opaque structure.
59 */
60 struct PSI_file_locker;
61 typedef struct PSI_file_locker 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
105 };
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 };
132 typedef struct PSI_file_info_v1 PSI_file_info_v1;
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. */
151  struct PSI_file *m_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 */
175 typedef 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 */
186 typedef 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 */
197 typedef 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 */
208 typedef 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 */
219 typedef 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 */
229 typedef 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 */
239 typedef 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 */
266 typedef 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 */
282 typedef 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 */
291 typedef 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 */
300 typedef 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 */
312 typedef 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 */
324 typedef 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 
328 typedef struct PSI_file_info_v1 PSI_file_info;
330 
331 /** @} (end of group psi_abi_file) */
332 
333 #endif /* COMPONENTS_SERVICES_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:42
Log info(cout, "NOTE")
Definition: os0file.h:85
static const char * category
Definition: sha2_password.cc:168
const char * filename
Definition: pfs_example_component_population.cc:64
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