Metakit 1.8.5

From WHATSNEW.TXT:

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   See below ("UPGRADING FROM 1.8.4") for important changes that may
   affect you when upgrading from an earlier release - especially if
   you use the c4_String class, or if you are using the MFC build.
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

WHAT IS THIS RELEASE?

  This new release is a minor release which offers substantial string
  search performance improvements, is much quicker in views with large
  numbers of properties, and offers a few new features, such as a new
  regular expression match for strings.  The MFC I/O model was dropped,
  in favor of using stdio in all configurations (you can still get any
  type of I/O mechanism you like by overriding c4_Strategy, as before).
  Any of the 3 configurations (MFC, STL, or UNIV) can be used in any
  context, now that c4_String and c4_File are gone from the public API.
  Only two minor bug fixes: affecting c4_View's GroupBy and Project.

WHAT HAS HAPPENED RECENTLY?

  There have been a few more ports, affecting the source in minor ways.
  The Tcl interface is now at revision 1.0.6, and is being used in a
  number of production-strength development projects and products.
  The Python interface has just been bumped to version 0.5, and though
  it appears quite stable, is still incomplete and a bit quirky to use.

WHAT HAS NOT HAPPENED?

  The documentation has not been updated.  The two undocumented changes
  are: all references to c4_String have been changed to "const char*",
  and: the c4_View::Match member does regexp matching (used like Find).

UPGRADING FROM 1.8.4:

This release makes some changes which are likely to affect your code.

For starters, the "c4_String" class is no longer available by default. If you use this class in your code, you'll need to include a header:

	#include <mk4.h>
	#include <mk4str.h> // <-- this defines the c4_String class

Furthermore, the following example will no longer work in this release:

	c4_View view = ...
	c4_StringProp pName ("name");
	const char* str = (c4_String) pName (view[123]);

The fix is to get rid of the c4_String temporary:

	const char* str = pName (view[123]);

Explanation: the API of Metakit has been changed to avoid *all* uses of c4_String (and CString in MFC). Instead, a small amount of internal buffering is used to be able to always return a "const char*" instead. (This change accounts for a whopping 2..3-fold performance increase!) The problem with the above code is the lifetime of c4_String objects.

Unfortunately, the above example is likely to not work either, because "str" now occasionaly points to a temporary buffer inside Metakit (the actual buffer depends on alignment - most of the time, str will just point directly into the memory mapped file). The "correct" solution is to allocate your own temporary buffer, as follows:

	c4_String temp = pName (view[123]);
	const char* str = temp;

Now, "str" will be correct as long as temp is valid / in scope.

  ********************************************************************
  ** STRINGS RETURNED BY METAKIT ARE NOW ONLY GUARANTEED TO REMAIN  **
  ** VALID UNTIL THE NEXT CALL OF *ANY* FUNCTION IN THE METAKIT API **
  ********************************************************************

Another major change, is that the MFC configuration now uses stdio for datafile I/O, instead of MFC's CFile class. Since stdio does not offer a portable way to implement access control, nor system-level flushing, nor file truncation, this has a number of consequences:

	- Opening a datafile for writing will no longer prevent other
	  readers/writers from opening the file as well.  If you used
	  to rely on this, you will need to make sure shared access
	  does not happen (any open for write of the file makes all
	  other accesses illegal, and can lead to file corruption.
	- Flushing used to call the Windows system flush as part of
	  the c4_Strategy::DataCommit call, to make sure data was
	  really on disk before a commit returns.  The effect of this
	  is that true "stable storage" is achieved, which is able
	  to recover, even from power failure at any point in the
	  commit sequence.  Without such flushing, there are a few
	  seconds during which the state on disk does not exactly
	  reflect the commited state.  Chances of problems are still
	  minute (only an immediately following commit could get into
	  trouble), but no longer impossible.
	- Files do not shrink, as they used to (but not predictably)
	  in some cases with MFC.  You can use the MKOPTIM example to
	  copy a file to a new one without gaps, to shrink it back.

If any of these issues matter to you, you will need to derive your own custom c4_Strategy class which implements to old behavior, using code present in src\mfc.cpp (see 1.8.4 - this file is no longer in 1.8.5).

Note that all the above changes *can* be implemented, even with stdio as I/O system, but they will need platform-dependent modifications.


From README.TXT:

The Metakit release is split up into a number of different packages, each of which can be downloaded as a separate archive.

ESSENTIAL INFORMATION

Not every file mentioned here is included in each package:

    These notes should be part of each archive - README
    For installation/build notes, see the file - INSTALL
    All the latest changes are summarized here - WHATSNEW
    Most documentation is in HTML, starting at - README.html

Each of archives below unpacks in a directory with the same name as the archive, there's no risk of overwriting when you unpack more than one.

FREELY DOWNLOADABLE RELEASES

The download URL for these files is: https://www.equi4.com/metakit/pub/

    mk4-1.8.5.tar.gz                0.3 Mb
    mk4-1.8.5.zip                   0.3 Mb
                The main evaluation package.  Sample code, HTML docs,
                headers, also the DLL (and import library) needed to
                use Metakit with the Microsoft Visual C++ 6.0 compiler.
    mk4*-1.8.5-tar.gz            (sizes vary)
                There are many platform-specific builds.  They only
                contain the main include files and one or more library
                builds for a specific platform (often "libmk4.a").

DEVELOPER RELEASES

These are available to registered users only. The registration fee of $25 entitles you to one year of updates, see the website for details.

    mk-dev-1.8.5.tar.gz             0.6 Mb
    mk-dev-1.8.5.zip                0.7 Mb
                Contains all include files (also inlined functions),
                sample programs, an extensive test suite with about
                a hundred small independent tests (lots of examples),
                the complete documentation, and a few binaries for
                Windows (compiled samples, as well as Mk4tcl + Mk4py).
                This is a convenient way to get it all in one archive.
    mk-dev-mfc-1.8.5.zip            1.9 Mb
                Compiled builds of Metakit, for use with MSVC and MFC.
                Configurations: Win 16/32, release/debug, static/dll.
    mk-dev-msvc-1.8.5.zip           2.7 Mb
                Compiled builds, again MSVC 6.0, but STL and Universal.
                Configurations: Win 16/32, release/debug, static/dll.

SOURCE CODE RELEASES

These are available to licensed users of Metakit only. The license fee is $165 for one year of updates ($90 for renewals), see the website.

    mk-src-1.8.5.tar.gz             0.7 Mb
    mk-src-1.8.5.zip                0.9 Mb
                Contains full docs, sources, and all make/project files.
                Everything except binaries in a single archive.