MySQL Bugs: #6149: doc lack about how to free memory used by libmysqlclient

Bug #6149	doc lack about how to free memory used by libmysqlclient
Submitted:	19 Oct 2004 0:32	Modified:	10 Feb 2005 19:25
Reporter:	Guilhem Bichot
Status:	Closed
Category:	Server	Severity:	S3 (Non-critical)
Version:	4.0	OS:	Any (all)
Assigned to:	Guilhem Bichot	Target Version:

Description:
Came from 
Date: Sat, 16 Oct 2004 18:11:47 -0400
From: "Jonathan A. Zdziarski" <jonathan@nuclearelephant.com>
To: valgrind-users@lists.sourceforge.net
Subject: [Valgrind-users] Output with no file or line #'s

Finally the thing is that user is linking with libmysqlclient, does mysql_init() so memory
is alloced for mysql (init_available_charsets() which calls my_once_alloc()) but that
memory is not explicitely freed at end (hence the Valgrind message). The way to free it is
mysql_server_end(), but it's unfortunately documented only in the "Embedded Server C API"
section of the manual.
Moving it into the section describing libmysqlclient is not enough, as mysql_server_end()
is a misleading name as it contains the "server" word.
So the proposal after discussion is to initiate a renaming:
mysql_server_init() -> mysql_library_init()
mysql_server_end() -> mysql_library_end()
new names nicely describes the fact that you should call these 2 functions as soon as you
use any MySQL library (libmysqlclient or libmysqld), and the fact that you do it once in
your program. mysql_server* would be deprecated.
mysql_library* would be defines for mysql_server*, in mysql.h:
#define mysql_library_init mysql_server_init. If we want we could in the future remove
mysql_server* but it's not strictly mandatory.

How to repeat:
see how-to-repeat

Precisions. Reason to not use mysql_end() as a new name for mysql_server_end() is that it
would make people believe that mysql_end is a counterpart for mysql_init() (see the
symmetry init/end in names), whereas in fact it's not (mysql_init() is a superset of the
true counterpart of mysql_server_end(), which is mysql_server_init()).
We would prefer to save the name mysql_end for when we need to implement some counterpart
to mysql_init() if needed.

Apart from updating the doc, new better names for the 2 API calls have been proposed in
bk commit - 4.1 tree (guilhem:1.2080)

Thank you for your bug report. This issue has been committed to our
source repository of that product and will be incorporated into the
next release.

If necessary, you can access the source repository and build the latest
available version, including the bugfix, yourself. More information 
about accessing the source trees is available at
    http://www.mysql.com/doc/en/Installing_source_tree.html

Additional info:

In 5.0 I just added
#define mysql_library_init mysql_server_init
#define mysql_library_end mysql_server_end
and will update doc.
ChangeSet@1.1843.1.2, 2005-02-04 13:53:16+01:00, guilhem@mysql.com

Back-ported to 4.1:
ChangeSet@1.2180, 2005-02-04 23:07:10+01:00, guilhem@mysql.com

Still not closed - impossible to push.

Docs team: this bug started as a doc issue; the things you could do (please):
- mention in changelog of 4.1.10 and 5.0.3 that we added mysql_library_init() and
mysql_library_end() as synonyms (#defines) for respectively mysql_server_init() and
mysql_server_end().
- fix the doc because it only mentions mysql_server_init/end as to be used for the
embedded server, whereas they should also be used (at least mysql_server_end) with
libmysqlclient. If you're linking your client program with libmysqlclient,
mysql_server_init (which does one-time alloc/initialization of some static structures of
libmysqlclient) is automatically called (once and only once) when you call mysql_init(),
so you don't need to explicitely call mysql_server_end(). But before your program exits,
the alloced structures need to be freed (otherwise it's not a memory leak but still
reported by memory leak detectors so it's not nice); this freeing job is done by calling
mysql_server_end(). mysql_server_end() is not mentioned in the section of libmysqlclient,
which is why at least 2 users had memory leak errors and didn't know how to free this
memory. As it sounded weird to call mysql_server_end() when you're a client, I just
added:
#define mysql_library_init mysql_server_init
#define mysql_library_end mysql_server_end
to sound simple: "every program which makes use of a MySQL *library* (libmysqld or
libmysqlclient) must call these".
About backward compatibility: as these are "defines", they can be used even if your client
is linked dynamically with pre-4.1.10 libmysqlclient.so, as long as the header files used
to compile were of 4.1.10 or newer.

Mentioned in 4.1.10 and 5.0.3 change notes.

Also added a note in the mysql_init() section
how these functions should be used.