mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-06 09:05:45 +00:00
320 lines
13 KiB
HTML
320 lines
13 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.71 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
|
|
<meta name="Author" content="Suresh Duddi">
|
|
<title>XPCOM Code FAQ</title>
|
|
</head>
|
|
<body>
|
|
|
|
<h2>
|
|
XPCOM Code FAQ</h2>
|
|
Suresh Duddi <<a href="mailto:dp@netscape.com">dp@netscape.com</a>>
|
|
<br>Last Modified: May 25 2000
|
|
<br>
|
|
<hr WIDTH="100%">
|
|
<br>I am documenting things randomly as I am replying to people's questions.
|
|
So this looks more like an FAQ.
|
|
<h3>
|
|
Table of Contents</h3>
|
|
|
|
<ol>
|
|
<li>
|
|
<a href="#What are the Global Objects that XPCOM maintains">What are the
|
|
Global Objects that XPCOM maintains</a></li>
|
|
|
|
<li>
|
|
<a href="#What are the static classes that XPCOM maintains">What are the
|
|
static classes that XPCOM maintains</a></li>
|
|
|
|
<li>
|
|
<a href="#Is there any restriction on which static class I should call fi">Is
|
|
there any restriction on which static class I should call first</a></li>
|
|
|
|
<li>
|
|
<a href="#What is the order of creation of the ServiceManager, ComponentM">What
|
|
is the order of creation of the ServiceManager, ComponentManager and Registry</a></li>
|
|
|
|
<li>
|
|
<a href="#Is there a global Registry being maintained">Is there a global
|
|
Registry being maintained</a></li>
|
|
|
|
<li>
|
|
<font color="#000000"><a href="#ComponentManager Vs ServiceManager">ComponentManager
|
|
Vs ServiceManager</a></font></li>
|
|
|
|
<li>
|
|
<a href="#ContractID Vs CLSID">ContractID Vs CLSID</a></li>
|
|
|
|
<li>
|
|
<a href="#How to set break points in component code">How to set breakpoints
|
|
in component code</a></li>
|
|
|
|
<li>
|
|
<a href="#Generating a log from xpcom:">Generating the XPCOM LOG</a>
|
|
<hr WIDTH="100%"></li>
|
|
</ol>
|
|
|
|
<h4>
|
|
<a NAME="What are the Global Objects that XPCOM maintains"></a>What are
|
|
the Global Objects that XPCOM maintains</h4>
|
|
|
|
<ul>mGlobalServiceManager
|
|
<br>mGlobalComponentManager</ul>
|
|
|
|
<h4>
|
|
<a NAME="What are the static classes that XPCOM maintains"></a>What are
|
|
the static classes that XPCOM maintains</h4>
|
|
|
|
<blockquote>nsComponentManager
|
|
<br>nsServiceManager</blockquote>
|
|
|
|
<h4>
|
|
<a NAME="Is there any restriction on which static class I should call fi"></a>Is
|
|
there any restriction on which static class I should call first</h4>
|
|
|
|
<blockquote>No restrictions. You can call any function from the static
|
|
classes nsComponentManager and nsServiceManager. XPCOM will do the right
|
|
thing to initialize itself at both places.
|
|
<p>Autoregistration() can happen only after Init_XPCOM() is called since
|
|
the registy might be required by SelfRegister() functions of the dlls and
|
|
it is only in Init_XPCOM() do we create register the RegistryFactory()
|
|
with the ComponentManager.</blockquote>
|
|
|
|
<h4>
|
|
<a NAME="What is the order of creation of the ServiceManager, ComponentM"></a>What
|
|
is the order of creation of the ServiceManager, ComponentManager and Registry</h4>
|
|
|
|
<blockquote>Init_XPCOM()
|
|
<blockquote>
|
|
<li>
|
|
create the global service manager</li>
|
|
|
|
<li>
|
|
create the global component manager and register as service with the global
|
|
service manager</li>
|
|
|
|
<li>
|
|
RegisterFactory(...RegistryFactory...) Register the RegistryFactory
|
|
with the component manager so that new registry objects can be created.</li>
|
|
</blockquote>
|
|
Now the hard problem is when to trigger Init_XPCOM() There are two static
|
|
objects nsComponentManager and nsServiceManager. Any function in either
|
|
of them can be called first. Today nsServiceManager::GetService() is the
|
|
first one that gets called. All the members of the static nsServiceManager
|
|
use the NS_GetGlobalServiceManager() to get to the global service manager.
|
|
All members of the static nsComponentManager use the NS_GetGlobalComponentManager()
|
|
to get to the global component manager. Hence if we trigger Init_XPCOM()
|
|
from both NS_GetGlobalComponentManager() and NS_GetGlobalServiceManager()
|
|
we will be safe.</blockquote>
|
|
|
|
<h4>
|
|
<a NAME="Is there a global Registry being maintained"></a>Is there a global
|
|
Registry being maintained</h4>
|
|
|
|
<blockquote>No. The nsIRegistry is designed to be lightweight access to
|
|
the registry. Consumers who need to access the registry should use the
|
|
component manager to create the their own registry access object. This
|
|
is required because the open() call is supported by the nsIRegistry() and
|
|
if we maintain a global registry arbitrating which registry file is opened
|
|
is going to be a major headach.
|
|
<p>The ContractID for the registry will be <font color="#990000">@mozilla.org/registry;1</font>
|
|
<br> </blockquote>
|
|
|
|
<h4>
|
|
<a NAME="ComponentManager Vs ServiceManager"></a><font color="#000000">ComponentManager
|
|
Vs ServiceManager</font></h4>
|
|
|
|
<blockquote><font color="#000000">ComponentManager is the only way for
|
|
component creation. ComponentManager always uses the component's factory
|
|
to create the component instance. Clients (code that calls CreateInstance()
|
|
to create and use a component) call the ComponentManager to create instances.
|
|
Components (the code that implemented NSRegisterSelf()) calls the ComponentManager
|
|
to register itself and gets called when a Client wants to instantiate a
|
|
component.</font>
|
|
<p><font color="#000000">ServiceManager is a convinience for getting singleton
|
|
components, components for which only one instance stays alive for the
|
|
entire application e.g Netlib. It enforces only one of a kind of a component
|
|
to exist. Hence the notion of getting a service not creating one. (as opposed
|
|
to the notion of Creating instances with the componentManager). ServiceManager
|
|
is a convenience because components can technically force singletonism
|
|
by making their factory return the same instance if one was created already.
|
|
The other big use of ServiceManager is the (still unimplemented) notion
|
|
of Shutting down a service.</font>
|
|
<p><b><i><font color="#000000">Client</font></i></b>
|
|
<ul>
|
|
<li>
|
|
<i><font color="#000000">When does a client use the service manager vs
|
|
component manager</font></i></li>
|
|
|
|
<br><font color="#000000">When a client knows that the component that they
|
|
are trying to instantiate is a singleton, they need to call service manager
|
|
instead of component manager. Clients dont have to worry about calling
|
|
the ComponentManager at all in this case. The ServiceManager will take
|
|
care of creating the instance if the first one doesn't exist already.</font>
|
|
<br>
|
|
<li>
|
|
<i><font color="#000000">When does a client use the Component Manager as
|
|
opposed to Service Manager</font></i></li>
|
|
|
|
<br><font color="#000000">When a client wants a private instance of a component,
|
|
they call the Component Manager. From the Clients point of view, a new
|
|
xpcom object creation happens everytime they call CreateInstance() Anything
|
|
else is an implementation detail that the Client need not worry about.</font>
|
|
<br>
|
|
<li>
|
|
<i><font color="#000000">How does a Client know that they have to instantiate
|
|
a singleton</font></i></li>
|
|
|
|
<br><font color="#000000">For now, the Client just has to know. There is
|
|
no way of telling which component is a Service and which isn't. In fact,
|
|
in todays xpcom (Mar 1999) any component can be accessed as a Service.
|
|
Use your judgement until there is a proper method or service manager is
|
|
eliminated. There is nothing even in the code that detects Services from
|
|
Instances.</font>
|
|
<p><b><font color="#CC0000">Need a solution for this. Email suggestion
|
|
to <a href="mailto:warren@netscape.com,dp@netscape.com">warren@netscape.com,
|
|
dp@netscape.com</a></font></b>
|
|
<br> </ul>
|
|
<b><i><font color="#000000">Component</font></i></b>
|
|
<ul>
|
|
<li>
|
|
<i><font color="#000000">Can a component enforce use only as a Service</font></i></li>
|
|
|
|
<br><font color="#000000">No. The notion of the ServiceManager is available
|
|
only to Clients.</font>
|
|
<p><font color="#000000">Note that at some points when a component wants
|
|
another component, it actually behaves as a client and hence follows the
|
|
rules of the Client above to either CreateInstance() or GetService() the
|
|
needed component.</font>
|
|
<p><b><tt><font color="#990000">Workaround:</font></tt></b><font color="#000000">
|
|
If however a component wants only one of its instances to exist and cannot
|
|
ensure that Clients understand well enough only to use the Service Manager
|
|
to get it, it can implement singletonism in its factory. Basically the
|
|
factory on first instance creation should hang on to the instance. On subsequence
|
|
instance creations, addref the instance it is holding to and return that
|
|
instead creating a new one.</font>
|
|
<ul>
|
|
<br><font color="#000000">E.g preferences does this.</font> Code sample
|
|
at
|
|
<a href="http://lxr.mozilla.org/seamonkey/source/modules/libpref/src/nsPref.cpp#621">nsPref.cpp
|
|
nsPrefFactory::CreateInstance()</a> and <a href="http://lxr.mozilla.org/seamonkey/source/modules/libpref/src/nsPref.cpp#227">nsPref.cpp
|
|
nsPref::GetInstance()</a> With this implementation, whether Clients get
|
|
to it by calling nsIServiceManager::GetService() or nsIComponentManager::CreateInstance(),
|
|
the same object will be returned hence guaranteeing singletonism.</ul>
|
|
|
|
<li>
|
|
<i><font color="#000000">Should a component do anything at creation to
|
|
become a Service</font></i></li>
|
|
|
|
<br><font color="#000000">No. Again, the notion of a ServiceManager is
|
|
available only to Clients.</font>
|
|
<br>
|
|
<li>
|
|
<i><font color="#000000">Can a component advertise that it is a service
|
|
so clients can use it as one</font></i></li>
|
|
|
|
<br>No. There isn't a way other than a comment in the interface of the
|
|
header file.</ul>
|
|
</blockquote>
|
|
|
|
<h4>
|
|
<a NAME="ContractID Vs CLSID"></a>ContractID Vs CLSID</h4>
|
|
|
|
<blockquote>ClassID or CLSID is the unique indentification of a component.
|
|
It is a structure of huge numbers generated by using uuidgen on a windows
|
|
box. It is represented as a string in documentation as {108d75a0-bab5-11d2-96c4-0060b0fb9956}
|
|
<p>ContractID is the string identification of an implementation of a component
|
|
the client is looking for. The representation takes a URI syntax. Eg. <i>@mozilla.org/network/protocol;1?description=Http Protocol Handler&name=http</i>
|
|
<br>Some simplify this to, ContractID is a more readable string form of a CLSID.
|
|
That is acceptable on the periphery. The ContractID is a Client thing. Components
|
|
register with component manager to claim that they are the implementation
|
|
for a ContractID. A component can register to be the implementation for multiple
|
|
ContractIDs (not implemented yet).
|
|
<p><b><i>Client</i></b>
|
|
<ul>
|
|
<li>
|
|
<i>Should CreateInstance() calls use ContractID or CLSID</i></li>
|
|
|
|
<br>ContractID is what Clients should use to CreateInstances. Clients should
|
|
not even know about the CLSID unless they are hell bent on creating a particular
|
|
implementation of a component.</ul>
|
|
<b><i>Component</i></b>
|
|
<ul>
|
|
<li>
|
|
<i>Should Components register with both a CID and ContractID</i></li>
|
|
|
|
<br>Absolutely.</ul>
|
|
</blockquote>
|
|
|
|
<h4>
|
|
<a NAME="How to set break points in component code"></a>How to set break
|
|
points in component code</h4>
|
|
|
|
<blockquote>
|
|
<blockquote>Since components are dynamically loaded only on demand, debugging
|
|
them could be a hard. Here are some tips to debugging components.
|
|
<p><b><i>Windows: VC5.0 VC6.0</i></b>
|
|
<blockquote>Include your component library in the Project->Settings, Additional
|
|
Dll. drop down. After that breakpoints can be enabled.</blockquote>
|
|
<b><i>Unix: gdb</i></b>
|
|
<blockquote>
|
|
<ul>
|
|
<li>
|
|
Let the program run until you are sure that your component is loaded. Type
|
|
Control-C. Now all symbols from your component will be available in gdb.
|
|
Put your breakpoints and restart the app. Gdb will complain that it cannot
|
|
set the breakpoint, and that it is temporarily disabling it, but when the
|
|
*.so is loaded, the breakpoint is enabled automatically. - <<a href="mailto:erik@netscape.com">Eric
|
|
Van Der Poel</a>></li>
|
|
</ul>
|
|
|
|
<ul>
|
|
<li>
|
|
I think typing "dir components" (assuming you're in dist/bin) will also
|
|
allow you to see the symbols in your stack the first time. - <<a href="mailto:alecf@netscape.com">Alec
|
|
Flett</a>></li>
|
|
</ul>
|
|
|
|
<ul>
|
|
<li>
|
|
Using XPCOM_BREAK_ON_LOAD environment variable:</li>
|
|
|
|
<p><br><tt>gdb> set env XPCOM_BREAK_ON_LOAD "necko:rdf"</tt>
|
|
<br><tt>gdb> r</tt>
|
|
<p>This will cause xpcom to break in the debugger after loading any dll
|
|
with substrings <tt>necko</tt> or <tt>rdf</tt> in them. At this point,
|
|
you could instruct the debugger to load the dll symbols and set breakpoint.
|
|
<p><tt>gdb> sha libnecko.so</tt>
|
|
<br><tt>gdb> b nsFunctionInNecko</tt></ul>
|
|
</blockquote>
|
|
<b><i>Mac: Codewarrior</i></b>
|
|
<blockquote>Just open the appropriate .xSYM file in the debugger; the debugger
|
|
will target the library when the application is run. - <<a href="mailto:sfraser@netscape.com">Simon
|
|
Fraser</a>></blockquote>
|
|
</blockquote>
|
|
</blockquote>
|
|
<a NAME="Generating a log from xpcom:"></a><b>Generating a log from xpcom:</b>
|
|
<blockquote>XPCOM provides log output. To enable the logging:
|
|
<blockquote><tt>[unix]</tt>
|
|
<br><tt>setenv NSPR_LOG_MODULES nsComponentManager:5</tt>
|
|
<br><tt>setenv NSPR_LOG_FILE xpcom.log</tt>
|
|
<p><tt>[win]</tt>
|
|
<br><tt>set NSPR_LOG_MODULES=nsComponentManager:5</tt>
|
|
<br><tt>set NSPR_LOG_FILE=xpcom.log</tt></blockquote>
|
|
Start your application after setting the above environment variables. Debug
|
|
log from xpcom would be in the file <tt>xpcom.log</tt></blockquote>
|
|
|
|
<p><br><a NAME="XPCOM Log analysis"></a><b>XPCOM Log analysis</b>
|
|
<blockquote><a href="http://lxr.mozilla.org/seamonkey/source/xpcom/doc/xpcom-log-analyze.sh">xpcom/doc/xpcom-log-analyze.sh</a>
|
|
is a script that does analysis of the xpcom log and prints out useful statistics
|
|
in html format. Usage is:
|
|
<blockquote><tt>xpcom-log-analyze.sh < xpcom.log > xpcom-log.html</tt>
|
|
<br><tt></tt> </blockquote>
|
|
</blockquote>
|
|
|
|
<hr WIDTH="100%">
|
|
</body>
|
|
</html>
|