=======================================================================

Itzam Core - C API Documentation
--------------------------------

Copyright 2006 Scott Robert Ladd. All rights reserved.

source: http://www.coyotegulch.com/products/itzam/locking.html

=======================================================================

Allowing multiple users and processes to access the same file is tricky.

Let's consider some of the complexities involved.

    1)  Access may come from different threads in the same application,
        or it might be from separate processes. Defining a database as
        "multi-user" is simply another way of saying that many processes
        can read and write the file simultaneously without conflict.
        
    2)  Identical code may behave differently on "similar" systems
        due to different device drivers and hardware configurations.
        Network files system may impose latencies that can not be
        controlled directly by the operating system.
        
    3)  Operating system are incompatible and inconsistent in their
        implementations of file locking. Even "UNIX" is not consistent
        across all implementations; Microsoft Windows supports several
        different techniques with inconsistent features.
        
Beginning with version 2.6.0, Itzam/Core provides a file locking 
abstraction; when compiled, the code identifies the target operating
system and adjusts its behavior.

A locking mechanism is specified when creating or opening a datafile
or index. Three types of locking are available, as identified by the
itzam_lock_mode enumeration:

    ITZAM_LOCK_NONE
        No locking is performed; calling the itzam_*_lock and
        itzam_*_unlock functions simple returns "true".
        
    ITZAM_LOCK_OS
        Locking is managed using operating system functions. On
        Linux, this is accomplished via fcntl() and fsync(); Windows
        uses the _locking and _commit functions. Locks are exclusive
        and block other lock requests until unlocked.
        
    ITZAM_LOCK_FILE
        A seceondary file is created to manage locking; while the
        file exists, a call to lock a file will block until the file
        is deleted via an unlock call.
        
The Itzam/Core library does *not* call locking functions itself. The
general pattern for code using Itzam/Core is as follows:

    itzam_datafile_lock(&db,false); // impose a read/write lock
    
    // perform several related read/write/remove operations
    
    itzam_datafile_unlock(&db); // unlock the file
    
Why not include automatic lock and unlock calls in the find/insert/
read/remove functions? Because doing so assumes that each operation is
atomic and is not connected to other operations.

Consider the act of performing a find on the database to determine if
a record exists, then reading it after asking the user a question. In
the time between find and the read, another process might remove the
record; therefore, the find and read must be "contained" within the
same lock, the ensure that the database matches at both calls.

You can see an example of this in the test/itzam_multi_test.c program.

=======================================================================
END
=======================================================================