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:	18 Oct 2004 22:32	Modified:	10 Feb 2005 18:25
Reporter:	Guilhem Bichot	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server	Severity:	S3 (Non-critical)
Version:	4.0	OS:	Any (all)
Assigned to:	Guilhem Bichot	CPU Architecture:	Any

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.