[pclasses-cvs] pclasses2/doc/manual pclasses2.lyx,1.2,1.3

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/doc/manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11970

Modified Files:
	pclasses2.lyx 
Log Message:
Added basic Factory and Plugin docs.

Index: pclasses2.lyx
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/doc/manual/pclasses2.lyx,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- pclasses2.lyx	24 Dec 2004 01:03:01 -0000	1.2
+++ pclasses2.lyx	25 Dec 2004 02:38:39 -0000	1.3
@@ -21,8 +21,8 @@
 \headheight 2cm
 \headsep 1cm
 \footskip 1cm
-\secnumdepth 3
-\tocdepth 3
+\secnumdepth 5
+\tocdepth 4
 \paragraph_separation skip
 \defskip medskip
 \quotes_language swedish
@@ -299,13 +299,135 @@
 Phoenix
 \layout Standard
 
-A shared object provider.
+A shared object provider, providing 
+\begin_inset Quotes sld
+\end_inset 
+
+phoenixing
+\begin_inset Quotes srd
+\end_inset 
+
+ behaviour on served objects.
+\layout Standard
+
+i can't bear to type all of this again.
+ See the huge amount of documentation in the API docs and at:
+\layout Itemize
+
+http://s11n.net/phoenix/
+\layout Itemize
+
+The 
+\begin_inset Quotes sld
+\end_inset 
+
+Context Singletons
+\begin_inset Quotes srd
+\end_inset 
+
+ paper at http://s11n.net/papers/ - that paper is where Phoenix was born.
+\layout Standard
+
+
+\series bold 
+Achtung
+\series default 
+: the Phoenix interface may be changed later to include Mutex/CriticalSection
+ support.
 \layout Subsection
 
 Factory
 \layout Standard
 
-Object factory interface.
+The Factory template type plays a major role in P, providing the interface
+ for key-based lookup of object factories.
+ What does that mean? It means the ability to dynamically load classes.
+\layout Subsubsection
+
+Registration
+\layout Standard
+
+To be loadable from Factory a type must register with the appropriate Factory.
+ All Factories parameterized on the same types share the same factories.
+ For the following examples we will assume Factory<MyType> is our Factory
+ type.
+\layout Standard
+
+There are several approaches to registering MyType (and it's subtypes) with
+ Factory<MyType>.
+ Here are some of the options:
+\layout Paragraph
+
+Supermacro
+\layout Standard
+
+Simply do the following:
+\layout Quote
+
+#define PFACREG_TYPE MyType
+\layout Quote
+
+#define PFACREG_TYPE_NAME 
+\begin_inset Quotes sld
+\end_inset 
+
+MyType
+\begin_inset Quotes srd
+\end_inset 
+
+
+\layout Quote
+
+#include <pclasses/FactoryReg.h>
+\layout Standard
+
+This should preferably (for linking reasons) be in MyType's header, but
+ it may actually be done in any number of places, including MyType's implementat
+ion file or a completely separate file which is linked in to your app or
+ a DLL.
+\layout Standard
+
+The FactorReg.h supermacro takes several options:
+\layout Itemize
+
+PFACREG_TYPE = the type you want to register.
+\layout Itemize
+
+PFACREG_TYPE_NAME = the string form of the name to use for classloading.
+\layout Itemize
+
+PFACREG_TYPE_INTERFACE = dubtypes of MyType should define this to MyType,
+ so that they get registered with the proper base classloader.
+\layout Itemize
+
+PFACREG_TYPE_IS_ABSTRACT = define this to any value if PFACREG_TYPE is abstract.
+ This installs a no-op factory for it.
+\layout Itemize
+
+PFACREG_CONTEXT = the factory context.
+ Don't set this unless you really, really know what you're doing.
+\layout Paragraph
+
+Factory::registerFactory()
+\layout Standard
+
+Factory::registerFactory() maps a class name to a factory.
+ See the class P::Hook::FactoryCreateHook for a class which provides simple
+ factory functions.
+\layout Standard
+
+It is common to call registerFactory() from global-scope initialization
+ code which gets activated during the static init phase of the code (pre-main()
+ or as a DLL is opened).
+ See 
+\family typewriter 
+<pclasses/FactoryReg.h>
+\family default 
+ or 
+\family typewriter 
+/srctree/test/CType.cpp
+\family default 
+ for examples.
 \layout Subsection
 
 Signals and Slots
@@ -344,14 +466,38 @@
 Plugin Module
 \layout Standard
 
-The types in this section all live in the namespace 
-\color red
-P::???
-\color default
-.
+The types in this section all live in the namespace P::Plugin.
 \layout Standard
 
-The Plugin module provides per-protocol, per-mime-type dynamic object loading.
+The Plugin module is an extension of the basic Factory support, extending
+ Factory to allow loading new types from DLLs.
+\layout Subsection
+
+Helpful free functions
+\layout Standard
+
+The following functions, all defined in namespace P::Plugin, all operate
+ on PluginManager<T>::instance().
+\layout Itemize
+
+pluginManager<T>() returns PluginManager<T>::instance().
+\layout Itemize
+
+addPluginDir<T>(string) adds a plugin dir.
+\layout Itemize
+
+addPlugin<T>( string ) loads the given plugin.
+\layout Itemize
+
+findPlugin<T>( string ) tries to locate a DLL for the given string, returning
+ the path on success.
+\layout Standard
+
+Note that addXXX() throw exceptions on errors.
+ This decision is under consideration, and it is possible that these functions
+ will be changed to never throw, for ease of client use.
+ Those who always want throwing behaviour may use PluginManager<T>'s API
+ directly.
 \layout Section
 
 System Module
@@ -363,23 +509,19 @@
 Filesystems
 \layout Subsubsection
 
-File (
-\color red
-FSFile, for consistency?
-\color default
-)
+File
 \layout Standard
 
 Encapsulates a filesystem file.
 \layout Subsubsection
 
-FSDirectory
+Directory
 \layout Standard
 
 Encapsulates a filesystem directory.
 \layout Subsubsection
 
-FSPath
+Path
 \layout Standard
 
 Encapsulates a filesystem path.