MySQL 8.4.3
Source Code Documentation
psi_socket_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_SOCKET_BITS_H
25#define COMPONENTS_SERVICES_BITS_PSI_SOCKET_BITS_H
26
27#ifndef MYSQL_ABI_CHECK
28#include <stddef.h> /* size_t */
29#endif
30
31#include <mysql/components/services/bits/my_io_bits.h> /* socklen_t */
33
34/**
35 @file mysql/components/services/bits/psi_socket_bits.h
36 Performance schema instrumentation interface.
37
38 @defgroup psi_abi_socket Socket Instrumentation (ABI)
39 @ingroup psi_abi
40 @{
41*/
42
43/**
44 Instrumented socket key.
45 To instrument a socket, a socket key must be obtained using @c
46 register_socket.
47 Using a zero key always disable the instrumentation.
48*/
49typedef unsigned int PSI_socket_key;
50
51/**
52 @def PSI_SOCKET_VERSION_1
53 Performance Schema Socket Interface number for version 1.
54 This version is supported.
55*/
56#define PSI_SOCKET_VERSION_1 1
57
58/**
59 @def PSI_CURRENT_SOCKET_VERSION
60 Performance Schema Socket Interface number for the most recent version.
61 The most current version is @c PSI_SOCKET_VERSION_1
62*/
63#define PSI_CURRENT_SOCKET_VERSION 1
64
65/**
66 Interface for an instrumented socket descriptor.
67 This is an opaque structure.
68*/
70typedef struct PSI_socket PSI_socket;
71
72/**
73 Interface for an instrumented socket operation.
74 This is an opaque structure.
75*/
78
79/** State of an instrumented socket. */
81 /** Idle, waiting for the next command. */
83 /** Active, executing a command. */
85};
87
88/** Operation performed on an instrumented socket. */
90 /** Socket creation, as in @c socket() or @c socketpair(). */
92 /** Socket connection, as in @c connect(), @c listen() and @c accept(). */
94 /** Socket bind, as in @c bind(), @c getsockname() and @c getpeername(). */
96 /** Socket close, as in @c shutdown(). */
98 /** Socket send, @c send(). */
100 /** Socket receive, @c recv(). */
102 /** Socket send, @c sendto(). */
104 /** Socket receive, @c recvfrom). */
106 /** Socket send, @c sendmsg(). */
108 /** Socket receive, @c recvmsg(). */
110 /** Socket seek, such as @c fseek() or @c seek(). */
112 /** Socket options, as in @c getsockopt() and @c setsockopt(). */
114 /** Socket status, as in @c sockatmark() and @c isfdtype(). */
116 /** Socket shutdown, as in @c shutdown(). */
118 /** Socket select, as in @c select() and @c poll(). */
122
123/**
124 Socket instrument information.
125 @since PSI_SOCKET_VERSION_1
126 This structure is used to register an instrumented socket.
127*/
129 /**
130 Pointer to the key assigned to the registered socket.
131 */
133 /**
134 The name of the socket instrument to register.
135 */
136 const char *m_name;
137 /**
138 The flags of the socket instrument to register.
139 @sa PSI_FLAG_SINGLETON
140 */
141 unsigned int m_flags;
142 /** Volatility index. */
144 /** Documentation. */
145 const char *m_documentation;
146};
148
149/**
150 State data storage for @c start_socket_wait_v1_t.
151 This structure provide temporary storage to a socket locker.
152 The content of this structure is considered opaque,
153 the fields are only hints of what an implementation
154 of the psi interface can use.
155 This memory is provided by the instrumented code for performance reasons.
156 @sa start_socket_wait_v1_t
157*/
159 /** Internal state. */
160 unsigned int m_flags;
161 /** Current socket. */
163 /** Current thread. */
165 /** Operation number of bytes. */
167 /** Timer start. */
168 unsigned long long m_timer_start{0};
169 /** Timer function. */
170 unsigned long long (*m_timer)(void);
171 /** Current operation. */
173 /** Source file. */
174 const char *m_src_file;
175 /** Source line number. */
177 /** Internal data. */
178 void *m_wait;
179};
181
182/**
183 Socket registration API.
184 @param category a category name (typically a plugin name)
185 @param info an array of socket info to register
186 @param count the size of the info array
187*/
188typedef void (*register_socket_v1_t)(const char *category,
189 struct PSI_socket_info_v1 *info,
190 int count);
191
192/**
193 Socket instrumentation initialisation API.
194 @param key the registered socket key
195 @param fd socket file descriptor
196 @param addr the socket ip address
197 @param addr_len length of socket ip address
198 @return an instrumented socket
199*/
200typedef struct PSI_socket *(*init_socket_v1_t)(PSI_socket_key key,
201 const my_socket *fd,
202 const struct sockaddr *addr,
203 socklen_t addr_len);
204
205/**
206 socket instrumentation destruction API.
207 @param socket the socket to destroy
208*/
209typedef void (*destroy_socket_v1_t)(struct PSI_socket *socket);
210
211/**
212 Record a socket instrumentation start event.
213 @param state data storage for the locker
214 @param socket the instrumented socket
215 @param op socket operation to be performed
216 @param count the number of bytes requested, or 0 if not applicable
217 @param src_file the source file name
218 @param src_line the source line number
219 @return a socket locker, or NULL
220*/
221typedef struct PSI_socket_locker *(*start_socket_wait_v1_t)(
222 struct PSI_socket_locker_state_v1 *state, struct PSI_socket *socket,
223 enum PSI_socket_operation op, size_t count, const char *src_file,
224 unsigned int src_line);
225
226/**
227 Record a socket instrumentation end event.
228 Note that for socket close operations, the instrumented socket handle
229 associated with the socket (which was provided to obtain a locker)
230 is invalid after this call.
231 @param locker a socket locker for the running thread
232 @param count the number of bytes actually used in the operation,
233 or 0 if not applicable, or -1 if the operation failed
234 @sa get_thread_socket_locker
235*/
236typedef void (*end_socket_wait_v1_t)(struct PSI_socket_locker *locker,
237 size_t count);
238
239/**
240 Set the socket state for an instrumented socket.
241 @param socket the instrumented socket
242 @param state socket state
243*/
245 enum PSI_socket_state state);
246
247/**
248 Set the socket info for an instrumented socket.
249 @param socket the instrumented socket
250 @param fd the socket descriptor
251 @param addr the socket ip address
252 @param addr_len length of socket ip address
253*/
254typedef void (*set_socket_info_v1_t)(struct PSI_socket *socket,
255 const my_socket *fd,
256 const struct sockaddr *addr,
257 socklen_t addr_len);
258
259/**
260 Bind a socket to the thread that owns it.
261 @param socket instrumented socket
262*/
264
267
268/** @} (end of group psi_abi_socket) */
269
270#endif /* COMPONENTS_SERVICES_BITS_PSI_SOCKET_BITS_H */
void(* register_socket_v1_t)(const char *category, struct PSI_socket_info_v1 *info, int count)
Socket registration API.
Definition: psi_socket_bits.h:188
PSI_socket_operation
Operation performed on an instrumented socket.
Definition: psi_socket_bits.h:89
struct PSI_socket_locker PSI_socket_locker
Definition: psi_socket_bits.h:77
PSI_socket_state
State of an instrumented socket.
Definition: psi_socket_bits.h:80
void(* set_socket_state_v1_t)(struct PSI_socket *socket, enum PSI_socket_state state)
Set the socket state for an instrumented socket.
Definition: psi_socket_bits.h:244
void(* set_socket_info_v1_t)(struct PSI_socket *socket, const my_socket *fd, const struct sockaddr *addr, socklen_t addr_len)
Set the socket info for an instrumented socket.
Definition: psi_socket_bits.h:254
void(* destroy_socket_v1_t)(struct PSI_socket *socket)
socket instrumentation destruction API.
Definition: psi_socket_bits.h:209
unsigned int PSI_socket_key
Instrumented socket key.
Definition: psi_socket_bits.h:49
void(* set_socket_thread_owner_v1_t)(struct PSI_socket *socket)
Bind a socket to the thread that owns it.
Definition: psi_socket_bits.h:263
void(* end_socket_wait_v1_t)(struct PSI_socket_locker *locker, size_t count)
Record a socket instrumentation end event.
Definition: psi_socket_bits.h:236
@ PSI_SOCKET_CLOSE
Socket close, as in shutdown().
Definition: psi_socket_bits.h:97
@ PSI_SOCKET_RECVMSG
Socket receive, recvmsg().
Definition: psi_socket_bits.h:109
@ PSI_SOCKET_STAT
Socket status, as in sockatmark() and isfdtype().
Definition: psi_socket_bits.h:115
@ PSI_SOCKET_SEND
Socket send, send().
Definition: psi_socket_bits.h:99
@ PSI_SOCKET_SENDMSG
Socket send, sendmsg().
Definition: psi_socket_bits.h:107
@ PSI_SOCKET_RECV
Socket receive, recv().
Definition: psi_socket_bits.h:101
@ PSI_SOCKET_BIND
Socket bind, as in bind(), getsockname() and getpeername().
Definition: psi_socket_bits.h:95
@ PSI_SOCKET_SEEK
Socket seek, such as fseek() or seek().
Definition: psi_socket_bits.h:111
@ PSI_SOCKET_CREATE
Socket creation, as in socket() or socketpair().
Definition: psi_socket_bits.h:91
@ PSI_SOCKET_CONNECT
Socket connection, as in connect(), listen() and accept().
Definition: psi_socket_bits.h:93
@ PSI_SOCKET_SENDTO
Socket send, sendto().
Definition: psi_socket_bits.h:103
@ PSI_SOCKET_SHUTDOWN
Socket shutdown, as in shutdown().
Definition: psi_socket_bits.h:117
@ PSI_SOCKET_RECVFROM
Socket receive, recvfrom).
Definition: psi_socket_bits.h:105
@ PSI_SOCKET_SELECT
Socket select, as in select() and poll().
Definition: psi_socket_bits.h:119
@ PSI_SOCKET_OPT
Socket options, as in getsockopt() and setsockopt().
Definition: psi_socket_bits.h:113
@ PSI_SOCKET_STATE_ACTIVE
Active, executing a command.
Definition: psi_socket_bits.h:84
@ PSI_SOCKET_STATE_IDLE
Idle, waiting for the next command.
Definition: psi_socket_bits.h:82
struct PSI_thread PSI_thread
Definition: psi_thread_bits.h:82
Types to make file and socket I/O compatible.
static int count
Definition: myisam_ftdump.cc:45
int my_socket
Definition: mysql.h:65
stdx::expected< native_handle_type, error_type > socket(int family, int sock_type, int protocol)
Definition: socket.h:63
static const char * category
Definition: sha2_password.cc:170
Performance schema instrumentation interface.
required string key
Definition: replication_asynchronous_connection_failover.proto:60
struct sockaddr sockaddr
Definition: sock_probe_win32.h:63
Instrumented artifact.
Definition: psi_bits.h:177
Socket instrument information.
Definition: psi_socket_bits.h:128
int m_volatility
Volatility index.
Definition: psi_socket_bits.h:143
PSI_socket_key * m_key
Pointer to the key assigned to the registered socket.
Definition: psi_socket_bits.h:132
const char * m_documentation
Documentation.
Definition: psi_socket_bits.h:145
const char * m_name
The name of the socket instrument to register.
Definition: psi_socket_bits.h:136
unsigned int m_flags
The flags of the socket instrument to register.
Definition: psi_socket_bits.h:141
State data storage for start_socket_wait_v1_t.
Definition: psi_socket_bits.h:158
unsigned long long m_timer_start
Timer start.
Definition: psi_socket_bits.h:168
enum PSI_socket_operation m_operation
Current operation.
Definition: psi_socket_bits.h:172
unsigned int m_flags
Internal state.
Definition: psi_socket_bits.h:160
struct PSI_socket * m_socket
Current socket.
Definition: psi_socket_bits.h:162
struct PSI_thread * m_thread
Current thread.
Definition: psi_socket_bits.h:164
const char * m_src_file
Source file.
Definition: psi_socket_bits.h:174
size_t m_number_of_bytes
Operation number of bytes.
Definition: psi_socket_bits.h:166
int m_src_line
Source line number.
Definition: psi_socket_bits.h:176
unsigned long long(* m_timer)(void)
Timer function.
Definition: psi_socket_bits.h:170
void * m_wait
Internal data.
Definition: psi_socket_bits.h:178
Interface for an instrumented socket descriptor.
Definition: psi_socket_bits.h:69