[GNUnet-SVN] r7311 - Extractor/doc

[gnunet]

Author: holindho
Date: 2008-06-23 10:05:07 -0600 (Mon, 23 Jun 2008)
New Revision: 7311

Modified:
   Extractor/doc/extractor.texi
Log:
update docs about thread-safety issues


Modified: Extractor/doc/extractor.texi
===================================================================
--- Extractor/doc/extractor.texi        2008-06-23 10:16:56 UTC (rev 7310)
+++ Extractor/doc/extractor.texi        2008-06-23 16:05:07 UTC (rev 7311)
@@ -176,7 +176,7 @@
 When you install @acronym{libextractor}, various plugins will be
 installed in the @file{lib/libextractor/} directory.  The main library
 will be installed as @file{lib/libextractor.so}.  Note that
address@hidden will attempt to find the plugins relativ to the
address@hidden will attempt to find the plugins relative to the
 path of the main library.  Consequently, a package manager can move
 the library and its plugins to a different location later --- as long
 as the relative path between the main library and the plugins is
@@ -260,9 +260,6 @@
 
 @findex EXTRACTOR_loadDefaultLibraries
 @findex EXTRACTOR_removeAll
address@hidden reentrant
address@hidden concurrency
address@hidden threads
 Clients should use the @verb{|EXTRACTOR_loadDefaultLibraries|}
 function to create an extractor list with the default set of plugins.
 Additional functions are provided for loading optional plugins.  Once
@@ -270,22 +267,43 @@
 @verb{|EXTRACTOR_removeAll|} to unload the plugins and free the
 extractor list.  Note that loading and unloading the plugins is a
 relatively costly operation.  If possible, programmers should avoid
-needlessly loading and unloading the plugins.  @acronym{libextractor}
-is reentrant, so the same set of plugins can be safely used
-concurrently by multiple threads.
+needlessly loading and unloading the plugins. 
 
address@hidden reentrant
address@hidden concurrency
address@hidden threads
address@hidden thread-safety
+All of the functions for loading and unloading plugins, including
address@hidden|EXTRACTOR_loadDefaultLibraries|} and 
@verb{|EXTRACTOR_removeAll|},
+are thread-safe, but not reentrant. The functions use operating system
+specific calls to dynamically load and unload objects, and in many cases,
+these calls are not thread-safe. In @acronym{libextractor} code, locking
+is used to protect access to these operating system specific calls. 
 
+Generally, @acronym{libextractor} is fully thread-safe and mostly reentrant.
+All plugin code is required to be reentrant, so the same set of plugins
+can be safely used concurrently by multiple threads. Reentrant functions, 
+naturally, do not protect their arguments (plugin or keyword lists) against
+concurrent access. For further information on @acronym{libextractor}'s
+thread-safety and reentrancy, also see the following chapters on
address@hidden usage.
+
 @node Extracting meta data
 @chapter Extracting meta data
 
 @findex EXTRACTOR_getKeywords
 @findex EXTRACTOR_getKeywords2
address@hidden reentrant
address@hidden concurrency
address@hidden threads
address@hidden thread-safety
 The main functions for extracting keywords with @acronym{libextractor}
 are @verb{|EXTRACTOR_getKeywords|} and
 @verb{|EXTRACTOR_getKeywords2|}.  The first argument to both functions
 is an extractor list which specifies the set of plugins that should be
 used for extracting meta data.   Both functions return a linked list
-of keywords (of type @verb{|EXTRACTOR_KeywordList|}).
+of keywords (of type @verb{|EXTRACTOR_KeywordList|}). Also, both
+functions are reentrant.
 
 The difference between the two functions is in how the file from which
 the meta data should be obtained is specified. The
@@ -326,6 +344,14 @@
 to perform further customizations using command-line options or a
 configuration file.
 
address@hidden reentrant
address@hidden concurrency
address@hidden threads
address@hidden thread-safety
+Like @verb{|EXTRACTOR_loadDefaultLibraries|} and 
address@hidden|EXTRACTOR_removeAll|}, these functions are thread-safe, but not
+reentrant. 
+
 @findex EXTRACTOR_addLibrary
 The @verb{|EXTRACTOR_addLibrary|} function can be used to add a
 single plugin to the front of the list of already loaded plugins.
@@ -376,6 +402,13 @@
 @node Utility functions
 @chapter Utility functions
 
address@hidden reentrant
address@hidden concurrency
address@hidden threads
address@hidden thread-safety
+This chapter describes various utility functions for
address@hidden usage. All of the functions are reentrant.
+
 @menu
 * Utility Constants::            Constants
 * Misc Keyword List::            Keyword List Functions