List:MySQL++« Previous MessageNext Message »
From:Warren Young Date:June 11 2005 2:23am
Subject:v2.0 release plan
View as plain text  
The basic concept of MySQL++ v2.0 is to roll up all of the ABI breakages 
that we've been putting off.  Ideally, this will be the last ABI 
breakage for a long while.  The mad god Murphy may have other plans, but 
even if we have to change the ABI again in the next major revision to 
correct unpopular changes, it's still in our best interest not to put 
off these changes any further.  The earlier we discover problems with 
these changes, the less time until we settle on a stable ABI.

We're therefore putting off major changes that shouldn't impact the ABI 
to v2.1 or later.  See the current Wishlist in the Subversion repository 
if you want a list of changes planned for future versions.

This plan is not engraved in stone.  Some of these changes may get 
pushed to v2.1, and other items from the Wishlist might get rolled up 
into v2.0.

The planned v2.0 changes are:

     o Create interface class for disabling exceptions, and derive all
       classes that currently can have exceptions disabled from this
       interface.  Then create an exception-disabling class that
       is designed to be created on the stack with a reference to
       one of these objects; while the disabler object is in scope,
       exceptions are disabled on the target object.  Side benefit:
       this will standardize the mechanism for temporarily disabling
       exceptions, which currently varies somewhat between classes.
       Also possible to do this with templates, using compile-time
       polymorphism.

     o Move SQLQueryNEParms into exceptions.h.

     o Hoist all common exception functionality up into a superclass,
       and derive all MySQL++ exceptions from that.

     o Extract Connection class's lock mechanism into a separate class,
       instances of which could be created on the stack so the lock
       is always relesased on function exit.  Derive Connection from
       an interface class ("Lockable"?) that provides lock and unlock
       functions.  Add a configure script option to allow this lock
       mechanism to use platform mutexes via the Boost.Threads library.
       Also derive Query from this new interface, as it also has a
       locking mechanism.

     o Change Connection::create_db() and drop_db() to return true on
       success.

     o Connection::create_db(), drop_db() and select_db() should take
       their arguments by reference, and be const.

     o Remove Connection::infoo() (Apparently an attempt to cope with
       typos for "info()".)

     o Rename Connection::read_options() to set_option().

     o Rename Connection::real_connect() to connect(), drop old
       connect() function, and set defaults for all parameters
       beyond what connect() supported.  Thus the API only changes
       for real_connect() users, and it's just a function rename.

     o Make Connection::execute() use mysql_real_query() instead of
       mysql_query() so it can handle binary data.

     o Remove query-building interface from Connection.  It just
       parallels most of the Query class interface, for little benefit.

     o Fold SQLQuery class into Query.

     o Use mysql_real_escape_string() instead of mysql_escape_string()
       within the Query::pprepare() function.  (In C API
       since 3.23.14.)  Depends on previous change, because
       mysql_real_escape_string() requires access to the current
       Connection object, to get the database's default character
       encoding.

     o See if we can use mysql_real_escape_string() in manip.cpp
       as well.  (This might end up being pushed into v2.1, if it's
       too tough.)

     o Give combined Query+SQLQuery class all the members it needs to
       look like a std::stringstream.   Use a private stringstream
       data member to hold the query-under-construction.

     o There are comments in sql_query.h saying "only here temporary".
       They've been there for literally years.  Time to decide what
       to do about them!

     o Set type to some default in ColData_Tmpl default ctor.

     o Fold RowTemplate class into Row.

     o Collapse mysql_* date and time classes into their subclasses,
       Date, Time, and DateTime.

     o Make dtors virtual in classes with virtual functions, to squish
       GCC 4.0 warning.  Also, go through each changed class looking
       for any code that allocates memory or other resources, and
       make sure they're released in the dtor.

     o Collapse multiple public and private sections of class
       mysql_type_info into one of each.  Also, consider renaming
       that class.

     o Collapse store(string&) and store(string&, bool) into a single
       function by making bool argument default to false.  Same for
       use() and execute().

     o Several of the value_list* and related functions in vallist.h
       and row.h can be collapsed into one by use of default
       parameters.  A conservative refactoring wouldn't change the
       API, but keep an open mind about whether a more aggressive
       change would be better in the end.

     o Try to collapse all SQLQueryParams::set() overloads into
       a single member by suitable use of default parameters.

     o Remove simp_list_b from vallist.h.  It's not used within the
       library, and it doesn't seem to be useful for end-user code.

     o Null's copy ctor should take its parameter by reference.

     o Remove the field name form of field_list().  It's pretty silly:
       it takes a field name as a paramter, and returns a field name!
       True, there's a type conversion going on here, but...

     o Change Row ctor to take the MYSQL_ROW by const reference.

     o Swap the definitions of Row::operator[] and lookup_by_name().
       That is, have the operator take a field name, and define a
       function (at()?) that takes a field index.  The original problem
       solved in 1.7.10 still exists, in that modern compilers won't
       let you overload the operator on both strings and integers,
       but the string form probably is the most useful.

     o Decide on a new soname scheme?  It'd be nice if the soname had
       some obvious relationship to the library version.  We could
       actually go with a 1:1 relationship, and simply override the
       default library symlink scheme to handle things correctly if
       libraries from the old scheme are still present.

     o Add a userman section severely summarizing ChangeLog, with a
       focus on API and ABI breakages.

     o Automatically define USE_WIN32_UCS2 in util.cpp when platform.h
       detects a Windows compiler.  Test with VC++ and Cygwin in
       -mno-cygwin mode.

     o Remove the exception handling stuff from all the simple*
       examples, so they earn their name.  Newbies get thrown into the
       deep end of the pool in simple1.cpp in the userman right now...

     o With previous change done, promote existing "notes on
       exceptions" section of tutorial into a new section, or even
       a new chapter.

     o Consider splitting "The Basics" section of tutorial into two
       parts, with the new EH discussion separating discussion of
       the examples that use EH and those that don't.

     o Add thread support to examples/Makefile.simple.  Commented-out
       by default, but available if required.

     o It may be possible to optimize the use of ColData in the return
       from Row::operator[]. Currently, that operator returns
       a temporary ColData object, which contains a std::string
       buffer which is initialized by a const char* pointer to
       data within the Row object.  Since the ColData object is
       temporary, you currently must copy the data a second time to
       store it when using Row::operator[].  If the end user just
       wants a const char*, this double copy could be prevented.
       See http://lists.mysql.com/plusplus/4451 for the proposal.

     o Relicense user manual.  Linux Documentation Project License v2.0
       is the current front-runner.

Thread
v2.0 release planWarren Young11 Jun
  • Re: v2.0 release planChris Frey11 Jun
    • Re: v2.0 release planWarren Young13 Jun
      • Re: v2.0 release planChris Frey14 Jun
        • Re: v2.0 release planWarren Young14 Jun
Re: v2.0 release planWarren Young13 Jun