MySQL Simple Asynchronous Client

Other solutions found:

After many search on internet, I do not found independant and usefull mysql asynchronous client. The alternative solutions are:

My lib:

The actual lib is beta. I search people for testing it and submit ideas. Is only tested with mysql 5. I think that is running also with MySQL 4.1

  • for the asynchronous The lib run with the same asynchronous mechanism that openssl: the I/O functions called, returns message "need write" or "need read", and never block.
  • The lib is linked with the official mysql client lib, for using authentication method and conversion network <-> host functions. This assure durability of the lib
  • The memory allocation are doing by the user code and not by the lib. With this choice, you can use your personnal memory manager.

Concepts:

  • In first step, you allocate memory for MYSAC pools. Each MYSAC struct manage connexion to MySQL server. Each MYSAC struct use 10384o (10240o just for buffering SQL requests and management responses)
  • In second step, you allocate buffer pool for containing responses. You can have big, medium and low memory buffers.
  • If you want speed in execution, you can prepare MySQL statements.
  • Send request: prepare request (or execute statement) and associate buffer with the request. when the request is terminated, you can dettach the buffer from MYSAC struct, and send other request. While the other request respond, you can use the buffer of the first request

Changes

  • version 0.6b - 2010-08-22:
    FEAT: Mysac may allocate memory and autoextend it for containing all the response .
    CLEANUP: fix licence to lgplv3. many files header are in gplv2.
    CLEANUP: remove statis inline functions BUG: some minor bug
  • version 0.5b - (2010-03-31):
    FEAT: Compile .so by default and rename static lib from limysac.a to libmysac-static.a
    BUG: fix compilation on x64 platform
  • version 0.4b - (2009-11-30):
    FEAT: Statement implementation
    FEAT: New io function. This function can be always called in place of context functions: mysac_send_database, mysac_send_database, mysac_send_query and mysac_connect
    BUILD: Use version without git
    BUG: Count columns in place of rows
    BUG: Wrong filedescriptor in exemple
    BUG: Function can not return status
    BUG: Compilation error
    BUG: Clean the exemple dir (makefile error)
  • version 0.3b - (2009-11-14):
    FEAT: Add two "set_query" functions FEAT: Add exemple
  • version 0.2b - (2009-10-12):
    CLEANUP: change licence from gplv2 to lgplv3
  • version 0.1b - (2009-05-24):
    CLEANUP: code cleanup
    DOC: updating doc / licence
    FEAT: add mysac_v_set_query for building query stdarg compliant
    FEAT: add mysac_get_res, this return resource
    FEAT: add many error messages
    FEAT: can use 64 bit responses (untested)
    FEAT: return value of last insert id
    FEAT: add function for browsing responses lines
    BUG: error with decoding fields > 64kB
    BUG: mysql response bloc decoding
    BUG: check minimun size of MYSAC_RES
  • version 0.0b-1 - initial release - (2009-02-04)

Download

date link md5sum
2010-08-22 mysac-0.6b.tar.gz be2128e8cb7430ed3e9364795ea06702
2010-03-31 mysac-0.5b.tar.gz 7e4653bfc623c5255cb0b7ba6193faa2
2009-11-30 mysac-0.4b.tar.gz 9fe242c9b4b27a97a73292072ec5837b
2009-11-14 mysac-0.3b.tar.gz a10c25d34c9860be3ccf9e7167c64299
2009-10-12 mysac-0.2b.tar.gz 2d6830a727b506f9cd72d114a0197d43
2009-05-24 mysac-0.1b.tar.gz 066086afdc7d87a11c6fe3c666341973
2009-02-04 mysac-0.0b-1.tar.gz 69427c65c00d3ed184790b9ae30b8825

List

  • you can send questions at:
  • Subscribe to the list:

API doc

mysac.h File Reference

#include <stdlib.h>
#include <stdarg.h>
#include <time.h>
#include <errno.h>
#include <string.h>
#include <sys/time.h>
#include <mysql/errmsg.h>
#include <mysql/mysql.h>

Include dependency graph for mysac.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


Data Structures

struct  mysac_list_head
union  MYSAC_ROW
struct  MYSAC_ROWS
struct  MYSAC_RES
struct  mysac_bind
struct  mysac

Defines

#define mysac_container_of(ptr, type, member)
#define mysac_list_entry(ptr, type, member)   mysac_container_of(ptr, type, member)
#define mysac_list_first_entry(ptr, type, member)   mysac_list_entry((ptr)->next, type, member)

Typedefs

typedef struct mysac_bind MYSAC_BIND
typedef struct mysac MYSAC

Functions

MYSAC * mysac_new (int buffsize)
void mysac_init (MYSAC *mysac, char *buffer, unsigned int buffsize)
void mysac_setup (MYSAC *mysac, const char *my_addr, const char *user, const char *passwd, const char *db, unsigned long client_flag)
int mysac_connect (MYSAC *mysac)
void mysac_close (MYSAC *mysac)
int mysac_get_fd (MYSAC *mysac)
int mysac_io (MYSAC *mysac)
int mysac_set_database (MYSAC *mysac, const char *database)
int mysac_send_database (MYSAC *mysac)
MYSAC_RES * mysac_init_res (char *buffer, int len)
MYSAC_RES * mysac_new_res (int chunk_size, int extend)
void mysac_free_res (MYSAC_RES *r)
int mysac_set_query (MYSAC *mysac, MYSAC_RES *res, const char *fmt,...)
int mysac_v_set_query (MYSAC *mysac, MYSAC_RES *res, const char *fmt, va_list ap)
int mysac_s_set_query (MYSAC *mysac, MYSAC_RES *res, const char *query)
int mysac_b_set_query (MYSAC *mysac, MYSAC_RES *res, const char *query, int len)
MYSAC_RES * mysac_get_res (MYSAC *mysac)
int mysac_send_query (MYSAC *mysac)
int mysac_set_stmt_prepare (MYSAC *mysac, unsigned long *stmt_id, const char *fmt,...)
int mysac_v_set_stmt_prepare (MYSAC *mysac, unsigned long *stmt_id, const char *fmt, va_list ap)
int mysac_s_set_stmt_prepare (MYSAC *mysac, unsigned long *stmt_id, const char *request)
int mysac_b_set_stmt_prepare (MYSAC *mysac, unsigned long *stmt_id, const char *request, int len)
int mysac_send_stmt_prepare (MYSAC *mysac)
int mysac_set_stmt_execute (MYSAC *mysac, MYSAC_RES *res, unsigned long stmt_id, MYSAC_BIND *values, int nb)
int mysac_send_stmt_execute (MYSAC *mysac)
int mysac_affected_rows (MYSAC *mysac)
unsigned int mysac_field_count (MYSAC_RES *res)
unsigned long mysac_num_rows (MYSAC_RES *res)
MYSAC_ROW * mysac_fetch_row (MYSAC_RES *res)
void mysac_first_row (MYSAC_RES *res)
MYSAC_ROW * mysac_cur_row (MYSAC_RES *res)
unsigned long mysac_insert_id (MYSAC *m)
int mysac_change_user (MYSAC *mysac, const char *user, const char *passwd, const char *db)
unsigned int mysac_errno (MYSAC *mysac)
const char * mysac_error (MYSAC *mysac)
const char * mysac_advance_error (MYSAC *mysac)

Detailed Description

Define Documentation

#define mysac_container_of ( ptr,
type,
member   ) 

Value:

({ \
        const typeof( ((type *)0)->member ) *__mptr = (ptr); \
        (type *)( (char *)__mptr - mysac_offset_of(type,member) );})
container_of - cast a member of a structure out to the containing structure

def imported from: linux-2.6.24/include/linux/kernel.h

Parameters:
ptr the pointer to the member.
type the type of the container struct this is embedded in.
member the name of the member within the struct.

#define mysac_list_entry ( ptr,
type,
member   )     mysac_container_of(ptr, type, member)

list_entry - get the struct for this entry

def imported from: linux-2.6.24/include/linux/list.h

Parameters:
ptr,: the &struct list_head pointer.
type,: the type of the struct this is embedded in.
member,: the name of the list_struct within the struct.

#define mysac_list_first_entry ( ptr,
type,
member   )     mysac_list_entry((ptr)->next, type, member)

list_first_entry - get the first element from a list

def imported from: linux-2.6.24/include/linux/list.h

Parameters:
ptr the list head to take the element from.
type the type of the struct this is embedded in.
member the name of the list_struct within the struct.
Note, that list is expected to be not empty.

Typedef Documentation

typedef struct mysac MYSAC

This contain the necessary for one mysql connection

typedef struct mysac_bind MYSAC_BIND

This contain list of values for statement binding

Function Documentation

const char* mysac_advance_error ( MYSAC *  mysac  ) 

For the connection specified by mysql, mysql_error() returns a null- terminated string containing the error message for the most recently invoked API function that failed. If a function didn't fail, the return value of mysql_error() may be the previous error or an empty string to indicate no error.

Parameters:
mysac Should be the address of an existing MYSQL structure.

int mysac_affected_rows ( MYSAC *  mysac  ) 

After executing a statement with mysql_query() returns the number of rows changed (for UPDATE), deleted (for DELETE), orinserted (for INSERT). For SELECT statements, mysql_affected_rows() works like mysql_num_rows().

Parameters:
mysac Should be the address of an existing MYSQL structure.
Returns:
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an UPDATE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the query returned an error or that, for a SELECT query, mysql_affected_rows() was called prior to calling mysql_store_result(). Because mysql_affected_rows() returns an unsigned value, you can check for -1 by comparing the return value to (my_ulonglong)-1 (or to (my_ulonglong)~0, which is equivalent).

int mysac_b_set_query ( MYSAC *  mysac,
MYSAC_RES *  res,
const char *  query,
int  len 
)

Initialize query

Parameters:
mysac Should be the address of an existing MYSAC structur.
res Should be the address of an existing MYSAC_RES structur.
query is a string containing the query
len is the len of the query
Returns:
0: ok, -1 nok

int mysac_b_set_stmt_prepare ( MYSAC *  mysac,
unsigned long *  stmt_id,
const char *  request,
int  len 
)

Prepare statement

Parameters:
mysac Should be the address of an existing MYSAC structur.
stmt_id is the receiver of the statement id
request is a string containing the query
len is the len of the query
Returns:
0: ok, -1 nok

int mysac_change_user ( MYSAC *  mysac,
const char *  user,
const char *  passwd,
const char *  db 
)

Changes the user and causes the database specified by db to become the default (current) database on the connection specified by mysql. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.

mysql_change_user() fails if the connected user cannot be authenticated or doesn't have permission to use the database. In this case, the user and database are not changed

This command resets the state as if one had done a new connect. It always performs a ROLLBACK of any active transactions, closes and drops all temporary tables, and unlocks all locked tables. Session system variables are reset to the values of the corresponding global system variables. Prepared statements are released and HANDLER variables are closed. Locks acquired with GET_LOCK() are released. These effects occur even if the user didn't change.

Parameters:
mysac Should be the address of an existing MYSQL structure.
user The user parameter contains the user's MySQL login ID. If user is NULL or the empty string "", the current user is assumed.
passwd The passwd parameter contains the password for user. If passwd is NULL, only entries in the user table for the user that have a blank (empty) password field are checked for a match.
db The db parameter may be set to NULL if you don't want to have a default database.
Returns:
CR_COMMANDS_OUT_OF_SYNC : Commands were executed in an improper order. CR_SERVER_GONE_ERROR : The MySQL server has gone away. CR_SERVER_LOST : The connection to the server was lost during the query. CR_UNKNOWN_ERROR : An unknown error occurred. ER_UNKNOWN_COM_ERROR : The MySQL server doesn't implement this command (probably an old server). ER_ACCESS_DENIED_ERROR : The user or password was wrong. ER_BAD_DB_ERROR : The database didn't exist. ER_DBACCESS_DENIED_ERROR : The user did not have access rights to the database. ER_WRONG_DB_NAME : The database name was too long.

void mysac_close ( MYSAC *  mysac  ) 

Closes a previously opened connection. mysql_close() also deallocates the connection handle pointed to by mysql if the handle was allocated automatically by mysql_init() or mysql_connect().

Parameters:
mysac Should be the address of an existing MYSQL structure.

int mysac_connect ( MYSAC *  mysac  ) 

Run network connexion and mysql authentication

Parameters:
mysac Should be the address of an existing MYSQL structure.
Returns:
MYERR_WANT_READ : want read socket MYERR_WANT_WRITE : want write socket CR_CONN_HOST_ERROR : Failed to connect to the MySQL server. CR_CONNECTION_ERROR : Failed to connect to the local MySQL server. CR_IPSOCK_ERROR : Failed to create an IP socket. CR_OUT_OF_MEMORY : Out of memory. CR_SOCKET_CREATE_ERROR : Failed to create a Unix socket. CR_UNKNOWN_HOST : Failed to find the IP address for the hostname. CR_VERSION_ERROR : A protocol mismatch resulted from attempting to connect to a server with a client library that uses a different protocol version. CR_SERVER_LOST : If connect_timeout > 0 and it took longer than connect_timeout seconds to connect to the server or if the server died while executing the init-command.

MYSAC_ROW* mysac_cur_row ( MYSAC_RES *  res  ) 

Get current row, dont touch row ptr

unsigned int mysac_errno ( MYSAC *  mysac  ) 

Returns the default character set name for the current connection.

Parameters:
mysac Should be the address of an existing MYSQL structure.
Returns:
The default character set name For the connection specified by mysql, mysql_errno() returns the error code for the most recently invoked API function that can succeed or fail. A return value of zero means that no error occurred. Client error message numbers are listed in the MySQL errmsg.h header file. Server error message numbers are listed in mysqld_error.h. Errors also are listed at Appendix B, Errors, Error Codes, and Common Problems.
Parameters:
mysac Should be the address of an existing MYSQL structure.

const char* mysac_error ( MYSAC *  mysac  ) 

For the connection specified by mysql, mysql_error() returns a null- terminated string containing the error message for the most recently invoked API function that failed. If a function didn't fail, the return value of mysql_error() may be the previous error or an empty string to indicate no error.

Parameters:
mysac Should be the address of an existing MYSQL structure.

MYSAC_ROW* mysac_fetch_row ( MYSAC_RES *  res  ) 

Retrieves the next row of a result set. mysql_fetch_row() returns NULL when there are no more rows to retrieve or if an error occurred.

The number of values in the row is given by mysql_num_fields(result).

The lengths of the field values in the row may be obtained by calling mysql_fetch_lengths(). Empty fields and fields containing NULL both have length 0; you can distinguish these by checking the pointer for the field value. If the pointer is NULL, the field is NULL; otherwise, the field is empty.

Parameters:
res Should be the address of an existing MYSAC_RES structure.
Returns:
A MYSAC_ROW structure for the next row. NULL if there are no more rows to retrieve or if an error occurred.

unsigned int mysac_field_count ( MYSAC_RES *  res  ) 

Returns the number of columns for the most recent query on the connection.

Parameters:
res Should be the address of an existing MYSAC_RES structure.
Returns:
number of columns

void mysac_first_row ( MYSAC_RES *  res  ) 

Set pointer on the first row, you can exec mysac_fetch_row, return it the first row;

void mysac_free_res ( MYSAC_RES *  r  ) 

Destroy MYSAC_RES structur This function free memory

int mysac_get_fd ( MYSAC *  mysac  ) 

This function return the mysql filedescriptor used for connection to the mysql server

Parameters:
mysac Should be the address of an existing MYSAC structure.
Returns:
mysql filedescriptor

MYSAC_RES* mysac_get_res ( MYSAC *  mysac  ) 

This function return the mysql response pointer

Parameters:
mysac Should be the address of an existing MYSAC structure.
Returns:
mysql response pointer

void mysac_init ( MYSAC *  mysac,
char *  buffer,
unsigned int  buffsize 
)

Initializes a MYSQL object. If mysql is a NULL pointer, the function allocates, initializes, and returns a new object. Otherwise, the object is initialized and the address of the object is returned. If mysql_init() allocates a new object, it is freed when mysql_close() is called to close the connection.

Parameters:
mysac Should be the address of an existing MYSAC structure.
buffer is ptr on the pre-allocated buffer
buffsize is the size of the buffer

MYSAC_RES* mysac_init_res ( char *  buffer,
int  len 
)

Initialize MYSAC_RES structur This function can not allocate memory, just use your buffer.

Parameters:
buffer this buffer must contain all the sql response. this size is: sizeof(MYSAC_RES) + ( sizeof(MYSQL_FIELD) * nb_field ) + ( different fields names )
and for each row: sizeof(MYSAC_ROWS) + ( sizeof(MYSAC_ROW) * nb_field ) + ( sizeof(unsigned long) * nb_field ) + ( sizeof(struct tm) for differents date fields of the request ) + ( differents strings returned by the request ) +

Parameters:
len is the len of the buffer
Returns:
MYSAC_RES. this function cannot be fail

unsigned long mysac_insert_id ( MYSAC *  m  ) 

Returns the value generated for an AUTO_INCREMENT column by the previous INSERT or UPDATE statement. Use this function after you have performed an INSERT statement into a table that contains an AUTO_INCREMENT field

http://dev.mysql.com/doc/refman/5.0/en/mysql-insert-id.html

Parameters:
m Should be the address of an existing MYSQL structure.
Returns:
the value generated for an AUTO_INCREMENT column

int mysac_io ( MYSAC *  mysac  ) 

this function call the io function associated with the current command. (mysac_send_database, mysac_send_query and mysac_connect)

Parameters:
mysac Should be the address of an existing MYSAC structure.
Returns:
0 is ok, or all errors associated with functions mysac_send_database, mysac_send_query and mysac_connect or MYERR_BAD_STATE : the function does nothing to do (is an error)

MYSAC* mysac_new ( int  buffsize  ) 

Allocates and initializes a MYSQL object. If mysql is a NULL pointer, the function allocates, initializes, and returns a new object. Otherwise, the object is initialized and the address of the object is returned. If mysql_init() allocates a new object, it is freed when mysql_close() is called to close the connection.

Parameters:
buffsize is the size of the buffer
Returns:
An initialized MYSAC* handle. NULL if there was insufficient memory to allocate a new object.

MYSAC_RES* mysac_new_res ( int  chunk_size,
int  extend 
)

Create new MYSAC_RES structur This function allocate memory

WARNING: If extend is set, you must use the function mysac_get_res for retrieving the resource pointer after each call att mysac_send_query.

Parameters:
chunk_size is the size allocated for the bloc
extend if is true, the block is extended if the initial memory does not enough. the extension size is the size of chunk_size

unsigned long mysac_num_rows ( MYSAC_RES *  res  ) 

Returns the number of rows in the result set.

mysql_num_rows() is intended for use with statements that return a result set, such as SELECT. For statements such as INSERT, UPDATE, or DELETE, the number of affected rows can be obtained with mysql_affected_rows().

Parameters:
res Should be the address of an existing MYSAC_RES structure.
Returns:
The number of rows in the result set.

int mysac_s_set_query ( MYSAC *  mysac,
MYSAC_RES *  res,
const char *  query 
)

Initialize query

Parameters:
mysac Should be the address of an existing MYSAC structur.
res Should be the address of an existing MYSAC_RES structur.
query is a string (terminated by ) containing the query
Returns:
0: ok, -1 nok

int mysac_s_set_stmt_prepare ( MYSAC *  mysac,
unsigned long *  stmt_id,
const char *  request 
)

Prepare statement

Parameters:
mysac Should be the address of an existing MYSAC structur.
stmt_id is the receiver of the statement id
query is a string (terminated by ) containing the query
Returns:
0: ok, -1 nok

int mysac_send_database ( MYSAC *  mysac  ) 

This send use database command

Parameters:
mysac Should be the address of an existing MYSQL structure.
Returns:
0 => ok MYSAC_WANT_READ MYSAC_WANT_WRITE ...

int mysac_send_query ( MYSAC *  mysac  ) 

Send sql query command

Parameters:
mysac Should be the address of an existing MYSAC structur.
Returns:
0 => ok MYSAC_WANT_READ MYSAC_WANT_WRITE ...

int mysac_send_stmt_execute ( MYSAC *  mysac  ) 

send stmt execute command

Parameters:
mysac Should be the address of an existing MYSQL structure.
Returns:

int mysac_send_stmt_prepare ( MYSAC *  mysac  ) 

Send sql query command

Parameters:
mysac Should be the address of an existing MYSAC structur.
stmt_id is pointer for storing the statement id
Returns:
0 => ok MYSAC_WANT_READ MYSAC_WANT_WRITE ...

int mysac_set_database ( MYSAC *  mysac,
const char *  database 
)

Build use database message

Parameters:
mysac Should be the address of an existing MYSQL structure.
database is the database name

int mysac_set_query ( MYSAC *  mysac,
MYSAC_RES *  res,
const char *  fmt,
  ... 
)

Initialize query

Parameters:
mysac Should be the address of an existing MYSAC structur.
res Should be the address of an existing MYSAC_RES structur.
fmt is the output format with the printf style
Returns:
0: ok, -1 nok

int mysac_set_stmt_execute ( MYSAC *  mysac,
MYSAC_RES *  res,
unsigned long  stmt_id,
MYSAC_BIND *  values,
int  nb 
)

Execute statement

Parameters:
mysac Should be the address of an existing MYSAC structur.
res Should be the address of an existing MYSAC_RES structur.
stmt_id the statement id
values is array of values send for the request
nb is number of values
Returns:
0: ok, -1 nok

int mysac_set_stmt_prepare ( MYSAC *  mysac,
unsigned long *  stmt_id,
const char *  fmt,
  ... 
)

Prepare statement

Parameters:
mysac Should be the address of an existing MYSAC structur.
stmt_id is the receiver of the statement id
fmt is the output format with the printf style
Returns:
0: ok, -1 nok

void mysac_setup ( MYSAC *  mysac,
const char *  my_addr,
const char *  user,
const char *  passwd,
const char *  db,
unsigned long  client_flag 
)

mysac_connect() attempts to establish a connection to a MySQL database engine running on host. mysql_real_connect() must complete successfully before you can execute any other API functions that require a valid MYSQL connection handle structure.

Parameters:
mysac The first parameter should be the address of an existing MYSQL structure. Before calling mysql_real_connect() you must call mysql_init() to initialize the MYSQL structure. You can change a lot of connect options with the mysql_options() call.
my_addr like "<ipv4>:<port>" "<ipv6>:<port>", "socket_unix_file" or NULL. If NULL, bind is set to socket 0
user The user parameter contains the user's MySQL login ID. If user is NULL or the empty string "", the current user is assumed.
passwd The passwd parameter contains the password for user. If passwd is NULL, only entries in the user table for the user that have a blank (empty) password field are checked for a match.
db is the database name. If db is not NULL, the connection sets the default database to this value.
client_flag The value of client_flag is usually 0, but can be set to a combination of the following flags to enable certain features:
Flag Name Flag Description CLIENT_COMPRESS Use compression protocol. CLIENT_FOUND_ROWS Return the number of found (matched) rows, not the number of changed rows. CLIENT_IGNORE_SPACE Allow spaces after function names. Makes all functions names reserved words.

int mysac_v_set_query ( MYSAC *  mysac,
MYSAC_RES *  res,
const char *  fmt,
va_list  ap 
)

Initialize query

Parameters:
mysac Should be the address of an existing MYSAC structur.
res Should be the address of an existing MYSAC_RES structur.
fmt is the output format with the printf style
ap is the argument list on format vprintf
Returns:
0: ok, -1 nok

int mysac_v_set_stmt_prepare ( MYSAC *  mysac,
unsigned long *  stmt_id,
const char *  fmt,
va_list  ap 
)

Prepare statement

Parameters:
mysac Should be the address of an existing MYSAC structur.
stmt_id is the receiver of the statement id
fmt is the output format with the printf style
ap is the argument list on format vprintf
Returns:
0: ok, -1 nok