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