[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r7311 - Extractor/doc
From: |
gnunet |
Subject: |
[GNUnet-SVN] r7311 - Extractor/doc |
Date: |
Mon, 23 Jun 2008 10:05:07 -0600 (MDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r7311 - Extractor/doc,
gnunet <=