MySQL 8.4.3
Source Code Documentation
mysql_async.h
Go to the documentation of this file.
1/* Copyright (c) 2019, 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 MYSQL_ASYNC_INCLUDED
25#define MYSQL_ASYNC_INCLUDED
26
27#include <mysql.h>
28
29/**
30 @file mysql_async.h
31
32 Declarations for asynchronous client communication.
33
34 @note this file should not be included as part of packaging.
35*/
36
37/**
38 This enum is to represent different asynchronous operations like reading the
39 network, writing to network, idle state, or complete state.
40*/
42 NET_ASYNC_OP_IDLE = 0, /**< default state */
43 NET_ASYNC_OP_READING, /**< used by my_net_read calls */
44 NET_ASYNC_OP_WRITING, /**< used by my_net_write calls */
45 NET_ASYNC_OP_COMPLETE /**< network read or write is complete */
46};
47
48/** Reading a packet is a multi-step process, so we have a state machine. */
50 NET_ASYNC_PACKET_READ_IDLE = 0, /**< default packet read state */
51 NET_ASYNC_PACKET_READ_HEADER, /**< read packet header */
52 NET_ASYNC_PACKET_READ_BODY, /**< read packet contents */
53 NET_ASYNC_PACKET_READ_COMPLETE /**< state to define if packet is
54 completely read */
55};
56
57/** Different states when reading a query result. */
59 NET_ASYNC_READ_QUERY_RESULT_IDLE = 0, /**< default state */
60 NET_ASYNC_READ_QUERY_RESULT_FIELD_COUNT, /**< read Ok or read field
61 count sent as part of
62 COM_QUERY */
63 NET_ASYNC_READ_QUERY_RESULT_FIELD_INFO /**< read result of above
64 COM_* command */
65};
66
67/** Sending a command involves the write as well as reading the status. */
69 NET_ASYNC_SEND_COMMAND_IDLE = 0, /**< default send command state */
70 NET_ASYNC_SEND_COMMAND_WRITE_COMMAND, /**< send COM_* command */
71 NET_ASYNC_SEND_COMMAND_READ_STATUS /**< read result of above COM_*
72 command */
73};
74
75/**
76 Async operations are broadly classified into 3 phases:
77 Connection phase, phase of sending data to server (which is writing phase)
78 and reading data from server (which is reading phase). Below enum describes
79 the same
80*/
85};
86
87/**
88 Represents the packet to be sent on wire asynchronously.
89*/
90struct io_vec {
91 void *iov_base; /**< Starting address */
92 size_t iov_len; /**< Number of bytes to transfer */
93};
94
95/** Local state for multipacket processing */
96struct mp_state {
104
105 void reset() {
109 mp_buf_length = 0;
111 mp_save_pos = 0;
112 mp_total_length = 0;
113 }
114};
115
116typedef struct NET_ASYNC {
117 /**
118 The position in buff we continue reads from when data is next
119 available
120 */
121 unsigned char *cur_pos;
122 /** Blocking state */
124 /** Our current operation */
126 /** How many bytes we want to read */
128 /**
129 Simple state to know if we're reading the first row, and
130 command/query statuses.
131 */
135
136 /** State when waiting on an async read */
138 /** Size of the packet we're currently reading */
140
141 /**
142 Headers and vector for our async writes; see net_serv.c for
143 detailed description.
144 */
145 unsigned char *async_write_headers;
149
150 /**
151 If the packet length is less than MAX_PACKET_LENGTH then use a static array
152 to hold the meta packet header. The array either holds the usual packet
153 header or a compressed meta packet header as following. The compressed
154 meta packet header is followwed by usual compresses packet heder that is
155 7 bytes in length.
156
157
158 Packet
159
160 Header
161 ~~~~~~~~~~~~~~~~~~~
162 B1 B2 B3 : Packet length
163 B4 : Packet number
164 ~~~~~~~~~~~~~~~~~~~
165
166 Payload
167 ~~~~~~~~~~~~~~~~~~~
168 B5 : COM_COMMAND
169 ~~~~~~~~~~~~~~~~~~~
170
171 Compressed Packet
172
173 Header
174 ~~~~~~~~~~~~~~~~~~~
175 B1 B2 B3 : Compress packet length
176 B4 : Compress Packet Nunmber
177 00 00 00 : Indicates following payload is uncompressed
178 ~~~~~~~~~~~~~~~~~~~
179
180 Payload
181 ~~~~~~~~~~~~~~~~~~~
182 B8 B9 B10 : Packet size
183 B11 : Packet number
184 B12 : COM_COMMAND
185 ~~~~~~~~~~~~~~~~~~~
186 */
188 NET_HEADER_SIZE + 1];
190
191 /** Keep track of compressed buffers */
193 /** Size of the compressed buffer */
196
198
202};
203
205void net_extension_free(NET *);
206
207#define NET_EXTENSION_PTR(N) \
208 ((NET_EXTENSION *)((N)->extension ? (N)->extension : NULL))
209
210#define NET_ASYNC_DATA(M) \
211 ((NET_EXTENSION_PTR(M)) ? (NET_EXTENSION_PTR(M)->net_async_context) : NULL)
212
213/**
214 Asynchronous operations are broadly classified into 2 categories.
215 1. Connection
216 2. Query execution
217 This classification is defined in below enum
218*/
224
225/**
226 Query execution in an asynchronous fashion is broadly divided into 3 states
227 which is described in below enum
228*/
234
235typedef struct MYSQL_ASYNC {
236 /** Buffer storing the rows result for cli_read_rows_nonblocking */
238 /** a pointer to keep track of the previous row of the current result row */
240 /** Context needed to track the state of a connection being established */
242 /** Status of the current async op */
244 /** Size of the current running async query */
246 /** If a query is running, this is its state */
248 /** context needed to support metadata read operation */
253 /** a pointer to keep track of the result sets */
255
256 /** the query parameters data */
258 /** the query parameters data length */
259 unsigned long async_qp_data_length;
260
262
264 const unsigned char *packet,
265 size_t len, bool *res);
267 NET *net, unsigned char command, const unsigned char *prefix,
268 size_t prefix_len, const unsigned char *packet, size_t packet_len,
269 bool *res);
270enum net_async_status my_net_read_nonblocking(NET *net, unsigned long *len_ptr);
271
273
274#endif /* MYSQL_ASYNC_INCLUDED */
#define COMP_HEADER_SIZE
compression header extra size
Definition: mysql_com.h:1123
#define NET_HEADER_SIZE
standard header size
Definition: mysql_com.h:1122
unsigned char uchar
Definition: my_inttypes.h:52
This file defines the client API to MySQL and also the ABI of the dynamically linked libmysqlclient.
NET_EXTENSION * net_extension_init()
Definition: net_serv.cc:100
struct MYSQL_ASYNC MYSQL_ASYNC
int mysql_get_socket_descriptor(MYSQL *mysql)
Definition: client.cc:4776
net_read_query_result_status
Different states when reading a query result.
Definition: mysql_async.h:58
@ NET_ASYNC_READ_QUERY_RESULT_FIELD_COUNT
read Ok or read field count sent as part of COM_QUERY
Definition: mysql_async.h:60
@ NET_ASYNC_READ_QUERY_RESULT_IDLE
default state
Definition: mysql_async.h:59
@ NET_ASYNC_READ_QUERY_RESULT_FIELD_INFO
read result of above COM_* command
Definition: mysql_async.h:63
void net_extension_free(NET *)
Definition: net_serv.cc:109
enum net_async_status net_write_command_nonblocking(NET *net, unsigned char command, const unsigned char *prefix, size_t prefix_len, const unsigned char *packet, size_t packet_len, bool *res)
Send a command to the server in asynchronous way.
Definition: net_serv.cc:787
net_async_read_packet_state
Reading a packet is a multi-step process, so we have a state machine.
Definition: mysql_async.h:49
@ NET_ASYNC_PACKET_READ_COMPLETE
state to define if packet is completely read
Definition: mysql_async.h:53
@ NET_ASYNC_PACKET_READ_BODY
read packet contents
Definition: mysql_async.h:52
@ NET_ASYNC_PACKET_READ_IDLE
default packet read state
Definition: mysql_async.h:50
@ NET_ASYNC_PACKET_READ_HEADER
read packet header
Definition: mysql_async.h:51
enum net_async_status my_net_read_nonblocking(NET *net, unsigned long *len_ptr)
net_async_block_state
Async operations are broadly classified into 3 phases: Connection phase, phase of sending data to ser...
Definition: mysql_async.h:81
@ NET_NONBLOCKING_READ
Definition: mysql_async.h:83
@ NET_NONBLOCKING_WRITE
Definition: mysql_async.h:84
@ NET_NONBLOCKING_CONNECT
Definition: mysql_async.h:82
net_send_command_status
Sending a command involves the write as well as reading the status.
Definition: mysql_async.h:68
@ NET_ASYNC_SEND_COMMAND_IDLE
default send command state
Definition: mysql_async.h:69
@ NET_ASYNC_SEND_COMMAND_READ_STATUS
read result of above COM_* command
Definition: mysql_async.h:71
@ NET_ASYNC_SEND_COMMAND_WRITE_COMMAND
send COM_* command
Definition: mysql_async.h:70
struct NET_ASYNC NET_ASYNC
mysql_async_query_state_enum
Query execution in an asynchronous fashion is broadly divided into 3 states which is described in bel...
Definition: mysql_async.h:229
@ QUERY_READING_RESULT
Definition: mysql_async.h:232
@ QUERY_IDLE
Definition: mysql_async.h:230
@ QUERY_SENDING
Definition: mysql_async.h:231
mysql_async_operation_status
Asynchronous operations are broadly classified into 2 categories.
Definition: mysql_async.h:219
@ ASYNC_OP_CONNECT
Definition: mysql_async.h:221
@ ASYNC_OP_UNSET
Definition: mysql_async.h:220
@ ASYNC_OP_QUERY
Definition: mysql_async.h:222
enum net_async_status my_net_write_nonblocking(NET *net, const unsigned char *packet, size_t len, bool *res)
Definition: net_serv.cc:839
net_async_operation
This enum is to represent different asynchronous operations like reading the network,...
Definition: mysql_async.h:41
@ NET_ASYNC_OP_IDLE
default state
Definition: mysql_async.h:42
@ NET_ASYNC_OP_READING
used by my_net_read calls
Definition: mysql_async.h:43
@ NET_ASYNC_OP_WRITING
used by my_net_write calls
Definition: mysql_async.h:44
@ NET_ASYNC_OP_COMPLETE
network read or write is complete
Definition: mysql_async.h:45
Definition: instrumented_condition_variable.h:32
Definition: buffer.h:45
net_async_status
Definition: plugin_auth_common.h:136
@ NET_ASYNC_COMPLETE
Definition: plugin_auth_common.h:137
Definition: mysql_async.h:235
MYSQL_ROWS ** prev_row_ptr
a pointer to keep track of the previous row of the current result row
Definition: mysql_async.h:239
enum mysql_async_query_state_enum async_query_state
If a query is running, this is its state.
Definition: mysql_async.h:247
unsigned int async_read_metadata_cur_field
Definition: mysql_async.h:252
MYSQL_FIELD * async_read_metadata_fields
Definition: mysql_async.h:250
struct mysql_async_connect * connect_context
Context needed to track the state of a connection being established.
Definition: mysql_async.h:241
MYSQL_ROWS async_read_metadata_data
Definition: mysql_async.h:251
struct MYSQL_RES * async_store_result_result
a pointer to keep track of the result sets
Definition: mysql_async.h:254
unsigned long async_qp_data_length
the query parameters data length
Definition: mysql_async.h:259
size_t async_query_length
Size of the current running async query.
Definition: mysql_async.h:245
MYSQL_DATA * rows_result_buffer
Buffer storing the rows result for cli_read_rows_nonblocking.
Definition: mysql_async.h:237
unsigned long * async_read_metadata_field_len
context needed to support metadata read operation
Definition: mysql_async.h:249
uchar * async_qp_data
the query parameters data
Definition: mysql_async.h:257
enum mysql_async_operation_status async_op_status
Status of the current async op.
Definition: mysql_async.h:243
Definition: mysql.h:163
Definition: mysql.h:121
Definition: mysql.h:340
Definition: mysql.h:153
Definition: mysql.h:300
Definition: mysql_async.h:116
struct io_vec * async_write_vector
Definition: mysql_async.h:146
enum net_async_operation async_operation
Our current operation.
Definition: mysql_async.h:125
size_t async_write_vector_size
Definition: mysql_async.h:147
unsigned char inline_async_write_header[NET_HEADER_SIZE+COMP_HEADER_SIZE+NET_HEADER_SIZE+1]
If the packet length is less than MAX_PACKET_LENGTH then use a static array to hold the meta packet h...
Definition: mysql_async.h:188
enum net_async_block_state async_blocking_state
Blocking state.
Definition: mysql_async.h:123
struct io_vec inline_async_write_vector[3]
Definition: mysql_async.h:189
bool read_rows_is_first_read
Simple state to know if we're reading the first row, and command/query statuses.
Definition: mysql_async.h:132
enum net_send_command_status async_send_command_status
Definition: mysql_async.h:133
size_t async_packet_length
Size of the packet we're currently reading.
Definition: mysql_async.h:139
size_t async_bytes_wanted
How many bytes we want to read.
Definition: mysql_async.h:127
unsigned char * cur_pos
The position in buff we continue reads from when data is next available.
Definition: mysql_async.h:121
unsigned char * async_write_headers
Headers and vector for our async writes; see net_serv.c for detailed description.
Definition: mysql_async.h:145
unsigned char ** compressed_write_buffers
Keep track of compressed buffers.
Definition: mysql_async.h:192
size_t compressed_buffers_size
Size of the compressed buffer.
Definition: mysql_async.h:194
enum net_async_read_packet_state async_packet_read_state
State when waiting on an async read.
Definition: mysql_async.h:137
size_t async_write_vector_current
Definition: mysql_async.h:148
enum net_read_query_result_status async_read_query_result_status
Definition: mysql_async.h:134
Definition: mysql_async.h:199
mysql_compress_context compress_ctx
Definition: mysql_async.h:201
NET_ASYNC * net_async_context
Definition: mysql_async.h:200
Definition: mysql_com.h:914
Represents the packet to be sent on wire asynchronously.
Definition: mysql_async.h:90
size_t iov_len
Number of bytes to transfer.
Definition: mysql_async.h:92
void * iov_base
Starting address.
Definition: mysql_async.h:91
Local state for multipacket processing.
Definition: mysql_async.h:96
size_t mp_buf_length
Definition: mysql_async.h:100
void reset()
Definition: mysql_async.h:105
ulong mp_total_length
Definition: mysql_async.h:103
size_t mp_first_packet_offset
Definition: mysql_async.h:99
uint mp_multi_byte_packet
Definition: mysql_async.h:101
net_async_status mp_status
Definition: mysql_async.h:97
ulong mp_save_pos
Definition: mysql_async.h:102
size_t mp_start_of_packet
Definition: mysql_async.h:98
Definition: client_async_authentication.h:164
Compression context information.
Definition: my_compress.h:74
command
Definition: version_token.cc:280