camel/README.mt

   1
   2 This version of camel is working towards being multi-thread safe
   3 (MT-SAFE).  At least, for the important api's.
   4
   5 This code has now been merged into the main head, but this file
   6 will remain here as a log of how it was done, incase any issues
   7 arise.  The ChangeLog of course has a much more detailed list
   8 of changes.
   9
  10 Intended method
  11 ===============
  12
  13 I intend working on it in several stages:
  14
  15 1. Making the api multi-threadable.  Basically removing some const-returns,
  16 and copying some data where it wasn't before.  The api should
  17 still continue to work if not being used in a multithreaded
  18 application.  There is not a significant amount of work here since
  19 this was more or less the intention all along.
  20
  21 Some functions where references to objects are returned may have to be
  22 changed slightly, so that refcounts are incremented before return.
  23 This doesn't affect much though.
  24
  25 camel_folder::get_message_info                          done
  26 camel_folder_summary::uid                               done
  27 camel_folder_summary::index                             done
  28 camel_folder::get_summary
  29         Needs to ref each summary item it points to.    done
  30 camel_folder::free_summary
  31         Needs to unref each summary item it points to.  done
  32 camel_folder_get_message_tag
  33         needs to copy the tag return
  34 camel_maildir_summary filename string
  35         should not be able to modify the string
  36         array contents after it has been added to
  37         the summary.
  38 camel_folder                                            done
  39         Make every camel-folder use a camel-folder-summary.
  40         This just reduces some of the code duplication,
  41         since everything but vee-folder does this already.
  42
  43 2. Adding high level locks for proof of concept.  The locks will
  44 be stored in private or global data, so the api should remain the same for
  45 non-threaded applications.
  46
  47 A per-folder lock which governs access to the folder
  48         summary, the folder file or
  49         communications socket, etc.                     done
  50 Locking for exceptions.                                 done
  51 Per store locks for internal stuff.                     done
  52 Per-service locks for various internal lists and
  53         caches                                          done
  54
  55 3. Further fine-grained locking where it can be done/is worthwhile.
  56
  57 A per-index lock for libibex                            done
  58 Locking for the search object                           half done
  59 Internal lock for the folder_summary itself
  60         So that searching can be detatched from other
  61         folder operations, etc.                         done
  62 Possibly a lock for access to parts of a mime-part
  63         or message
  64
  65 4. A method to cancel operations.
  66
  67 Individual outstanding operations must be cancellable, and not just
  68 'all current operations'.  This will probably not use pthread_cancel
  69 type of cancelling.
  70
  71 This will however, probably use a method for starting a new thread,
  72 through camel, that can then be cancelled, and/or some method of
  73 registering that a thread can be cancelled.  Blocking states within
  74 camel, within that thread, will then act as checkpoints for if the
  75 operation, and if it is cancelled, the operation will abort
  76 (i.e. fail, with an appropriate exception code).
  77
  78 Operation cancelling should also function when the application is not
  79 multi-threaded.  Not sure of the api for this yet, probably a callback
  80 system.  Hopefully the api for both scenarios can be made the same.
  81
  82 Other thoughts
  83 ==============
  84
  85 Basically much of the code in camel that does the actual work does NOT
  86 need to be thread safe to make it safely usable in an mt context.
  87
  88 camel-folder, camel-summary, camel-imap-search, and the camel-service
  89 classes (at least) are the important ones to be made multithreaded.
  90
  91 For other things, they are either resources that are created
  92 one-off (for example, camel-mime-message, and its associated
  93 parts, like camel-internet-address), or multithreadedness
  94 doesn't make a lot of sense - e.g. camel-stream, or camel-mime-parser.
  95
  96 So basically the approach is a low-risk one.  Adding the minimum
  97 number of locks to start with, and providing further fine-grained
  98 locks as required.  The locks should not need to be particularly
  99 fine-grained in order to get reasonable results.
 100
 101 Log of changes
 102 ==============
 103
 104 Changed CamelFolder:get_message_info() to return a ref'd copy, requiring
 105 all get_message_info()'s to have a matching free_message_info().
 106
 107 Moved the CamelFolder frozen changelog data to a private structure.
 108
 109 Added a mutex for CamelFolder frozen changelog stuff (it was just easy
 110 to do, although it isn't needed yet).
 111
 112 Added a single mutex around all other CamelFolder functions that need
 113 it, this is just the first cut at mt'edness.
 114
 115 Fixed all camel-folder implementations that call any other
 116 camel-folder functions to call via virtual methods, to bypass the locks.
 117
 118 Added camel-store private data.
 119
 120 Added a single mutex lock for camel-store's folder functions.
 121
 122 Added camel-service private data.
 123
 124 Added a single mutex lock for camel-service's connect stuff.
 125
 126 Added a mutex for remote-store stream io stuff.
 127
 128 Added a mutex for imap, so it can bracket a compound command
 129 exclusively.  Pop doesn't need this since you can only have a single
 130 folder per store, and the folder interface is already forced
 131 single-threaded.
 132
 133 Added mutex for camel-session, most operations.
 134
 135 Running the tests finds at least 1 deadlock so far.  Need to
 136 work on that.
 137
 138 Fixed get_summary to ref/unref its items.
 139
 140 Removed the global folder lock from the toplevel
 141 camel_folder_search(), each implementation must now handle locking.
 142
 143 Fixed the local-folder implementation of searching.  imap-folder
 144 searching should already be mt-safe through the command lock.
 145
 146 Fixed imap summary to ref/unref too.
 147
 148 Built some test cases, and expanded the test framework library to
 149 handle multiple threads.  It works!
 150
 151 Next, added a recursive mutex class, so that locking inside imap had
 152 any chance of working.  Got imap working.
 153
 154 Moved the camel folder summary into the base folder class, and fixed
 155 everything to use it that way.
 156
 157 Made the vfolder use a real camel-folder-summary rather than a
 158 hashtable + array that it was using, and probably fixed some problems
 159 which caused evolution-mail not to always catch flag updates.  Oh, and
 160 made it sync/expunge all its subfolders when sync/expungeing.
 161
 162 Made the camel-folder summary completely mt-safe.
 163
 164 Removed all of the locks on the folder functions dealing directly with
 165 the summary, so now for example all summary lookups will not be
 166 interupted by long operations.
 167
 168 Made the nntp newsrc thing mt-safe, because of some unfortunate
 169 sideeffect of it being called from the summary interaction code in
 170 nntp-folder.
 171