Skip to content

M
mariadb
Commit 3c033351 authored by tim@black.box's avatar tim@black.box
Browse files
Options

Improve libmsyql_r and libmysqld sections of manual.

parent c0670fca
Hide whitespace changes
Inline Side-by-side
Showing with 75 additions and 143 deletions
.bzrignore
View file @ 3c033351
......@@ -424,3 +424,4 @@ vio/test-ssl
vio/test-sslclient
vio/test-sslserver
vio/viotest-ssl
libmysqld/mf_iocache.cc
Docs/manual.texi
View file @ 3c033351
......@@ -43711,12 +43711,12 @@ shell> ./configure --enable-thread-safe-client
This will create a thread-safe client library @code{libmysqlclient_r}.
@code{--enable-thread-safe-client}. This library is thread safe per
connection. You can let two threads share the same connection as long
as you do the following:
connection. You can let two threads share the same connection with
the following caveats:
@itemize @bullet
@item
Two threads can't send a query to the MySQL at the same time on
Two threads can't send a query to the MySQL server at the same time on
the same connection. In particular, you have to ensure that between a
@code{mysql_query()} and @code{mysql_store_result()} no other thread is using
the same connection.
......@@ -43725,9 +43725,9 @@ Many threads can access different result sets that are retrieved with
@code{mysql_store_result()}.
@item
If you use @code{mysql_use_result}, you have to ensure that no other thread
is asking anything on the same connection until the result set is closed.
is using the same connection until the result set is closed.
However, it really is best for threaded clients that share the same
connection to use @code{mysql_use_result()}.
connection to use @code{mysql_store_result()}.
@item
If you want to use multiple threads on the same connection, you must
have a mutex lock around your @code{mysql_query()} and
......@@ -43741,14 +43741,14 @@ establish and release a mutex lock.
@end itemize
You need to know the following if you have a thread that is calling
MySQL functions, but that thread has not created the connection to the
MySQL functions which did not create the connection to the
MySQL database:
When you call @code{mysql_init()} or @code{mysql_connect()}, MySQL will
create a thread specific variable for the thread that is used by the
debug library (among other things).
If you have in a thread call a MySQL function, before a thread has
If you call a MySQL function, before the thread has
called @code{mysql_init()} or @code{mysql_connect()}, the thread will
not have the necessary thread specific variables in place and you are
likely to end up with a core dump sooner or later.
......@@ -43769,7 +43769,7 @@ specific variables.
@end enumerate
You may get some errors because of undefined symbols when linking your
client with @code{mysqlclient_r}. In most cases this is because you haven't
client with @code{libmysqlclient_r}. In most cases this is because you haven't
included the thread libraries on the link/compile line.
@node libmysqld, , Threaded clients, C
......@@ -43796,22 +43796,22 @@ full-featured MySQL server inside the client application. The
main benefits are increased speed and more simple management for
embedded applications.
The API is identical for the embedded MySQL version and MySQL
The API is identical for the embedded MySQL version and the
client/server version. To change an old threaded application to use the
embedded library, on normall only have to add calls to the following
embedded library, you normally only have to add calls to the following
functions:
@multitable @columnfractions .25 .7
@item @code{mysql_server_init()} @tab Should be called before any other other MySQL function is called, preferably early in the @code{main()} function.
@item @code{mysql_server_end()} @tab Should be called before doing an exit of your program.
@item @code{mysql_thread_init()} @tab Should be called in all threads you are created that will access MySQL.
@item @code{mysql_server_end()} @tab Should be called before your program exits.
@item @code{mysql_thread_init()} @tab Should be called in each thread you create that will access MySQL.
@item @code{mysql_thread_end()} @tab Should be called before calling @code{pthread_exit()}
@end multitable
and link your code with @code{libmysqld.a} instead of @code{libmysqlclient.a}.
Then you must link your code with @code{libmysqld.a} instead of @code{libmysqlclient.a}.
The above @code{mysql_server_xxx} functions are also included in
@code{libmysqld.a} to allow you to change between the embedded and the
@code{libmysqlclient.a} to allow you to change between the embedded and the
client/server version by just linking your application with the right
library. @xref{mysql_server_init}.
......@@ -43823,8 +43823,8 @@ To get a @code{libmysqld} library you should configure MySQL with the
@code{--with-embedded-server} option.
When you link your program with @code{libmysqld}, you must also include
the system specific @code{pthread} libraries and some libraries that
@code{mysqld} uses. You can get the full list of libraries by executing
the system-specific @code{pthread} libraries and some libraries that
the MySQL server uses. You can get the full list of libraries by executing
@code{mysql_config --libmysqld-libs}.
The correct flags for compiling and linking a threaded program
......@@ -43835,8 +43835,6 @@ functions in your code.
@subsubsection Restrictions when using the Embedded MySQL Server
The embedded server has the following limitations:
(Some of these limitations can be changed by editing the @code{mysql_embed.h}
include files and recompiling MySQL)
@itemize @bullet
@item
......@@ -43849,6 +43847,9 @@ No stack trace on core dump.
No internal RAID support.
@end itemize
Some of these limitations can be changed by editing the @file{mysql_embed.h}
include file and recompiling MySQL.
@node libmysqld options, libmysqld TODO, libmysqld restrictions, libmysqld
@subsubsection Using option files with the embedded server
......@@ -43902,13 +43903,13 @@ designed to give enough details to understand the problem,
without the clutter that is a necessary part of a real
application.
To try out the example, create an @file{example} directory
To try out the example, create an @file{test_libmysqld} directory
at the same level as the mysql-4.0 source directory. Save
the @file{example.c} source and the @file{GNUmakefile} in the
directory, and run GNU @file{make} from inside the @file{example}
the @file{test_libmysqld.c} source and the @file{GNUmakefile} in the
directory, and run GNU @file{make} from inside the @file{test_libmysqld}
directory.
@file{example.c}
@file{test_libmysqld.c}
@example
/*
* A simple example client, using the embedded MySQL server library
......@@ -43919,28 +43920,30 @@ directory.
#include <stdio.h>
#include <stdlib.h>
enum on_error @{ E_okay, E_warn, E_fail @};
static void die(MYSQL *db, char *fmt, ...);
MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query, enum on_error on_error);
void db_do_query(MYSQL *db, const char *query);
const char *server_groups[] = @{ "test_client_SERVER", "server", NULL @};
const char *server_groups[] = @{
"test_libmysqld_SERVER", "embedded", "server", NULL
@};
int
main(int argc, char **argv)
@{
MYSQL *one, *two;
/* This must be called before any other mysql functions.
/* mysql_server_init() must be called before any other mysql
* functions.
*
* You can use mysql_server_init(0, NULL, NULL), and it will
* initialize the server using groups = @{ "server", "embedded", NULL @}.
* initialize the server using groups = @{
* "server", "embedded", NULL
* @}.
*
* In your $HOME/.my.cnf file, you probably want to put:
[test_client_SERVER]
[test_libmysqld_SERVER]
language = /path/to/source/of/mysql/sql/share/english
* You could, of course, modify argc and argv before passing
......@@ -43952,13 +43955,13 @@ language = /path/to/source/of/mysql/sql/share/english
* If you link this client against the normal mysqlclient
* library, this function is just a stub that does nothing.
*/
mysql_server_init(argc, argv, server_groups);
mysql_server_init(argc, argv, (char **)server_groups);
one = db_connect("test");
two = db_connect(NULL);
db_do_query(one, "show table status", E_fail);
db_do_query(two, "show databases", E_fail);
db_do_query(one, "show table status");
db_do_query(two, "show databases");
mysql_close(two);
mysql_close(one);
......@@ -43969,14 +43972,14 @@ language = /path/to/source/of/mysql/sql/share/english
exit(EXIT_SUCCESS);
@}
void
static void
die(MYSQL *db, char *fmt, ...)
@{
va_list ap;
va_start(ap, fmt);
vfprintf(stderr, fmt, ap);
va_end(ap);
putc('\n', stderr);
(void)putc('\n', stderr);
if (db)
db_disconnect(db);
exit(EXIT_FAILURE);
......@@ -43988,7 +43991,12 @@ db_connect(const char *dbname)
MYSQL *db = mysql_init(NULL);
if (!db)
die(db, "mysql_init failed: no memory");
mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "simple");
/*
* Notice that the client and server use separate group names.
* This is critical, because the server will not accept the
* client's options, and vice versa.
*/
mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test_libmysqld_CLIENT");
if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
die(db, "mysql_real_connect failed: %s", mysql_error(db));
......@@ -44001,130 +44009,57 @@ db_disconnect(MYSQL *db)
mysql_close(db);
@}
/*
* show_query: this code is snagged from mysql.cc; this function
* is intended to be used internally to db_do_query()
*/
static char *
show_query(MYSQL *db)
@{
MYSQL_RES *res;
MYSQL_FIELD *field;
MYSQL_ROW row;
char sep[256], *psep = sep;
char *is_num = 0;
char *err = 0;
unsigned int length = 1; /* initial "|" */
unsigned int off;
if (!(res = mysql_store_result(db)))
return mysql_error(db);
if (!(is_num = malloc(mysql_num_fields(res))))
@{
err = "out of memory";
goto err;
@}
/* set up */
*psep++ = '+';
while ((field = mysql_fetch_field(res)))
@{
unsigned int len = strlen(field->name);
if (len < field->max_length)
len = field->max_length;
if (len < 2 && !IS_NOT_NULL(field->flags))
len = 2; /* \N */
field->max_length = len + 1; /* bending the API... */
len += 2; length += len + 1; /* " " before, " |" after */
if (length >= 255)
@{
err = "row too long";
goto err;
@}
memset(psep, '-', len); psep += len;
*psep++ = '+';
*psep = '\0';
@}
/* column headings */
puts(sep);
mysql_field_seek(res,0);
fputc('|',stdout);
for (off=0; (field = mysql_fetch_field(res)) ; off++)
@{
printf(" %-*s|",field->max_length, field->name);
is_num[off]= IS_NUM(field->type);
@}
fputc('\n',stdout);
puts(sep);
/* rows */
while ((row = mysql_fetch_row(res)))
@{
(void) fputs("|",stdout);
mysql_field_seek(res,0);
for (off=0 ; off < mysql_num_fields(res); off++)
@{
field = mysql_fetch_field(res);
printf(is_num[off] ? "%*s |" : " %-*s|",
field->max_length, row[off] ? (char*) row[off] : "NULL");
@}
(void) fputc('\n',stdout);
@}
puts(sep);
err:
if (is_num)
free(is_num);
mysql_free_result(res);
return err;
@}
void
db_do_query(MYSQL *db, const char *query, enum on_error on_error)
db_do_query(MYSQL *db, const char *query)
@{
char *err = 0;
if (mysql_query(db, query) != 0)
goto err;
if (mysql_field_count(db) > 0)
@{
if ((err = show_query(db)))
MYSQL_RES *res;
MYSQL_ROW row, end_row;
int num_fields;
if (!(res = mysql_store_result(db)))
goto err;
num_fields = mysql_num_fields(res);
while ((row = mysql_fetch_row(res)))
@{
(void)fputs(">> ", stdout);
for (end_row = row + num_fields; row < end_row; ++row)
(void)printf("%s\t", row ? (char*)*row : "NULL");
(void)fputc('\n', stdout);
@}
(void)fputc('\n', stdout);
@}
else if (mysql_affected_rows(db))
printf("Affected rows: %lld [%s]\n", mysql_affected_rows(db), query);
else
(void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
return;
err:
switch (on_error) @{
case E_okay:
break;
case E_warn:
fprintf(stderr, "db_do_query failed: %s [%s]\n",
err ? err : mysql_error(db), query);
break;
case E_fail:
die(db, "db_do_query failed: %s [%s]",
err ? err : mysql_error(db), query);
break;
@}
die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
@}
@end example
@file{GNUmakefile}
@example
# Set this to your mysql source directory
m := ../mysql-4.0
# This assumes the MySQL software is installed in /usr/local/mysql
inc := /usr/local/mysql/include/mysql
lib := /usr/local/mysql/lib
# If you have not installed the MySQL software yet, try this instead
#inc := $(HOME)/mysql-4.0/include
#lib := $(HOME)/mysql-4.0/libmysqld
CC := cc
CPPFLAGS := -I$m/include -D_THREAD_SAFE -D_REENTRANT
CC := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
CFLAGS := -g -W -Wall
LDFLAGS := -static
LDLIBS = $(embed_libs) -lz -lm -lcrypt
# You can change -lmysqld to -lmysqlclient to use the
# client/server library
LDLIBS = -L$(lib) -lmysqld -lz -lm -lcrypt
ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD
......@@ -44134,10 +44069,6 @@ else
LDLIBS += -lpthread
endif
# Standard libraries. This example assumes MySQL is in /usr/local/mysql
embed_libs := -L/usr/local/mysql/lib/mysql/ -lmysqld
# This works for simple one-file test programs
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7