MySQL  8.0.27
Source Code Documentation
mysql_async.h
Go to the documentation of this file.
1 /* Copyright (c) 2019, 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 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 */
89 struct io_vec {
90  void *iov_base; /**< Starting address */
91  size_t iov_len; /**< Number of bytes to transfer */
92 };
93 
94 typedef 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 */
170  unsigned char **compressed_write_buffers;
171  /** Size of the compressed buffer */
174 
178 };
179 
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 */
199 };
200 
201 /**
202  Query execution in an asynchronous fashion is broadly divided into 3 states
203  which is described in below enum
204 */
209 };
210 
211 typedef 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);
246 enum 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:1119
#define NET_HEADER_SIZE
standard header size
Definition: mysql_com.h:1118
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.
struct MYSQL_ASYNC MYSQL_ASYNC
int mysql_get_socket_descriptor(MYSQL *mysql)
Definition: client.cc:4567
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:787
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
NET_EXTENSION * net_extension_init()
Definition: net_serv.cc:99
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:839
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:42
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:337
Definition: mysql.h:152
Definition: mysql.h:297
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:910
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:140
Compression context information.
Definition: my_compress.h:73
command
Definition: version_token.cc:279