[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-pim
Subject:    [Kde-pim] icaldir Proposal
From:       Mark Bucciarelli <mark () easymailings ! com>
Date:       2005-10-19 15:24:39
Message-ID: 20051019152439.GD3484 () rabbit
[Download RAW message or body]

This is a MIME-formatted message.  If you see this text it means that your
E-mail software does not support MIME-formatted messages.


As part of the daemon proposal discussion, we have been tossing around 
at least three distinct issues:

    1. memory usage (e.g., indexing)

    2. mediating concurrent access to a shared ical data store.

    3. the daemon itself.

As Reinhold noted, the first two can be considered independently of the 
third.

The most important issue for me is #2. The attached icaldir proposal 
attempts to address this issue.  I look forward to your comments!

m

["icaldir.txt" (text/plain)]

$Id: icaldir.txt,v 1.2 2005/10/19 12:16:18 mark Exp $

                             icaldir 

CONTENTS

    I.    OVERVIEW
    II.   FILE LAYOUT 
    III.  SEMANTICS
    IV.   FEEDBACK


I.) OVERVIEW

    This document proposes a maildir-like approach for storing 
    iCalendar data.  The motivation is to provide a way for 
    multiple client applications to coordinate concurrent updates 
    to a iCalendar data that is stored on a shared drive.

    Currently, most client programs that access iCalendar data 
    (for example, KDE's KOrganizer [1], Apple's iCal [2],  
    Mozilla's Sunbird [3], the PHP iCalendar [4]) read and save 
    iCalendar data in one large file.  This works fine if there 
    is one program updating the calendar data but breaks down if 
    multiple clients are updating the same dataset.

    The approach outlined below is inspired by and borrows 
    heavily from the maildir format [5].  The main differences 
    are:

        - maildir does not have to handle changes to the contents 
          of an email, once written to disk, and

        - with multiple iCalendar clients, the concept of an 
          unread directory (the "new" maildir) and the associated 
          status flags are not relevant.

    If the following conditions are met, the icaldir format 
    satisfies the "ACID test" [6].

        1.  A transaction is limited to changing one and only one 
            calendar object.

        2.  There are no consistency checks required between 
            iCalendar objects.

        3.  The contents of the cur directory are the data.

        4.  The "move" command is atomic.
        
    The icaldir format is designed to be tolerant of network 
    transience.  For example, if an client application begins an 
    update transaction, but crashes or loses network connectivity 
    before completing the transaction,
    
        - there is no data loss and
          
        - the lock file goes stale after a configurable timeout 
          period so other clients are free to update that object.


II.) FILE LAYOUT 


    .../icaldir
        |
        +- lockduration
        |
        +- vcalendar_header
        |
        +- vcalendar_footer
        |
        +- /cur 
        |
        +- /tmp
    

II.A.) The lockduration file

    The lockduration file is used to determine if an existing 
    lock is stale.  It contains one line, the number of seconds 
    after which a lock becomes stale.


II.B.) The vcalendar_header file

    This stores any iCalendar header information that comes 
    before the iCalendar objects start; for example,

        BEGIN:VCALENDAR
        CALSCALE: GREGORIAN
        X-WR-TIMEZONE; VALUE=TEST:US/Pacific

II.C.) The vcalendar_footer file

    Contains any iCalendar information that comes after the 
    iCalendar objects end; for example,

        END:VCALENDAR 

II.D.) The cur directory

    This directory holds one file for every iCalendar object.  
    The file names are created using the maildir specification, 
    with the additional rule that the event type (Journal, Event, 
    Todo) is also put in the file name.

    TODO: Write this up in more detail.

II.E.) The tmp directory

    A temporary working directory.  No persistent data is stored here.


III.) SEMANTICS


III.A.) Create a New Calendar Object

    1. Generate a file name (follow same rules as maildir).

    2. Write file to tmp directory using this file name.
       Use the file name as object's iCalendar UID property.

    3. Move file from tmp to cur directory.


III.B.) Update a Calendar Object

    1. Create new file in tmp with same filename as event plus a 
       .lock extension.

    2. If file creation successful, go to step 6.

        3. Create a temporary file in tmp with file name using 
           maildir rules.

        4. Compute difference in seconds between the timestamps 
           on the file created in step 3 and the lock file that 
           already exists in tmp (which was the reason file 
           creation failed in step 2).

        5. If the difference in seconds is greater than the value 
           stored in the lockduration file, then overwrite lock 
           file and goto step 7.

        6. Stop--the iCalendar object is being updated by another 
           process.

    7. Write the new version of the event to this tmp file.

    8. Move file from tmp to cur, discarding .lock extension.


III.C.) Delete a Calendar Object

    1. Delete the object's file from the cur directory.

    Note that since an update transaction is effectively an 
    atomic delete + insert that it is legal for one client 
    process to reinsert an event after another process has 
    deleted it.


IV.) FEEDBACK

    Please send any comments on this document to kdepim@kde.org.


[1] http://pim.kde.org/korganizer

[2] TODO

[3] TODO

[4] http://phpicalendar.net/

[5] http://cr.yp.to/proto/maildir.html

[6] ACID is an acronym for

        Atomic    : either all changes associated with a 
                    transaction take place, or none do.

        Consistent: the database is transformed from one valid 
                    state to another valid state.

        Isolated  : a transaction's results are not visible to 
                    other transactions until the transaction is 
                    complete.

        Durable   : once committed, the results of a transaction 
                    are permanent and survive future system and 
                    media failures.


_______________________________________________
kde-pim mailing list
kde-pim@kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
kde-pim home page at http://pim.kde.org/

[prev in list] [next in list] [prev in thread] [next in thread]