diff --git a/xpcom/doc/MemoryTools.html b/xpcom/doc/MemoryTools.html deleted file mode 100644 index c3a70be36314..000000000000 --- a/xpcom/doc/MemoryTools.html +++ /dev/null @@ -1,1166 +0,0 @@ - - - - Memory Tools - - - - - - - -
-

How to debug memory leaks/refcnt leaks

-
- -
Last update: September 5, 2000
- -

What tools do we have?

- The mozilla team has developed a number of memory analysis tools to augment -commercial tools like Purify. These can help us more quickly spot and fix -memory leaks and memory bloat (our term for taking up too much memory, aka -footprint). Here's a list of what we have at our disposal: - - More description on each of these will be provided below. -

How to turn on refcnt/memory logging

- Assuming you have a build with refcnt logging enabled (we'll tell you how -to do that next), here's what you have to do to use it. All of the following -environment variables can be set to any of these values: - - The log environment variables are: -
XPCOM_MEM_BLOAT_LOG
- -
-
If this environment variable is set then xpcom will use the -"bloat" trackers. The bloat trackers gather data for the BloatView output -that occurs when the program exits, when about:bloat is loaded, or a call -to nsTraceRefcnt::DumpStatistics is made. -

When an addref/release/ctor/dtor call is made, the data is logged -and attributed to the particular data type.

-

By default enabling this environment variable will cause the BloatView -software to dump out the entire database of collected data. If all you want -to see is that data for objects that leaked, set the environment variable -XPCOM_MEM_LEAK_LOG.

-
- XPCOM_MEM_LEAK_LOG -
This is basically a subset of XPCOM_MEM_BLOAT_LOG, and -only shows classes that had object that were leaked, instead of statistics -for all classes.
- XPCOM_MEM_REFCNT_LOG -
Setting this environment variable enables refcount tracing. -
-Only enable this for severe pain (unless you are using refcount tracing or -leaky, see below). What this does is to enable logging (to stdout) of each -and every call to addref/release without discrimination to the types involved. -The output includes mapping the call-stacks at the time of the call to symbolic -forms (on platforms that support this) and thus will be *very* *VERY* *VERY* -slow. Did I say slow? It is not as slow when using XPCOM_MEM_LOG_CLASSES -and XPCOM_MEM_LOG_OBJECTS
- XPCOM_MEM_COMPTR_LOG -
This environment variable enables logging of additions -and releases of objects into nsCOMPtrs. This is currently only enabled on -Linux.
- XPCOM_MEM_ALLOC_LOG -
For losing architectures (those that don't have stack-crawl -software written for them), xpcom supports logging at the *call site* to AddRef/Release -using the usual cpp __FILE__ and __LINE__ number macro expansion hackery. -This results in slower code, but at least you get *some* data about where -the leaks might be occurring from.
- XPCOM_MEM_LEAKY_LOG -
For platforms that support leaky, xpcom will endeavor -to find at run time the symbols "__log_addref" and "__log_release" and if -found, instead of doing the slow painful stack crawls at program execution -time instead it will pass the buck to the leaky software. This will allow -your program to actually run in user friendly real time, but does require -that your platform support leaky. Currently only linux supports leaky.
-
- In addition, the following variable may be set to a list of class names: -
XPCOM_MEM_LOG_CLASSES
- -
-
Instead of slowing to a useless, instead -you can slow to a meer crawl by using this option. When enabled, the xpcom -logging software will look for the XPCOM_MEM_LOG_CLASSES environment variable -(for platforms that support getenv). The variable contains a comma separated -list of names which will be used to compare against the type's of the objects -being logged. For example: -
env XPCOM_MEM_LOG_CLASSES=nsWebShell XPCOM_MEM_REFCNT_LOG=1 -./apprunner
- will show you just the AddRef/Release calls to instances of nsWebShell while -running apprunner.Note that setting XPCOM_MEM_LOG_CLASSES will also list -the serial number of each object that leaked in the "bloat log" (that -is, the file specified by the XPCOM_MEM_BLOAT_LOG variable). An object's -serial number is simply a unique number, starting at one, that is assigned -to the object when it is allocated.
-
- You may use an object's serial number with the following variable to further -restrict the reference count tracing: -
XPCOM_MEM_LOG_OBJECTS
- -
-
Set this variable to a comma-separated -list of object serial number or ranges of serial number, e.g., - 1,37-42,73,165. When this is set, -along with XPCOM_MEM_LOG_CLASSES and XPCOM_MEM_REFCNT_LOG, a stack track -will be generated for only the specific objects that you list. For -example, -
env XPCOM_MEM_LOG_CLASSES=nsWebShell -XPCOM_MEM_LOG_OBJECTS=2 XPCOM_MEM_REFCNT_LOG=1 ./apprunner
- will dump stack traces to the console for the 2nd nsWebShell - object that gets allocated, and nothing else.
-
- -
-

1. BloatView

- BloatView dumps out per-class statistics on allocations and refcounts, and -provides gross numbers on the amount of memory being leaked broken down by -class. Here's a sample of the BloatView output: 
== BloatView: ALL (cumulative) LEAK AND BLOAT STATISTICS

     |<------Class----->|<-----Bytes------>|<----------------Objects---------------->|<--------------References-------------->|
                          Per-Inst   Leaked    Total      Rem      Mean       StdDev     Total      Rem      Mean       StdDev
   0 TOTAL                     193  2480436   316271    12852 ( 5377.07 +/-  5376.38)   410590    16079 ( 2850.93 +/-  2849.79)
   1 StyleSetImpl               32        0        8        0 (    3.88 +/-     3.15)     6304        0 (    7.18 +/-     6.63)
   2 SinkContext                32        0       19        0 (    1.87 +/-     1.04)        0        0 (    0.00 +/-     0.00)
   3 nsXPCClasses               12        0        2        0 (    1.00 +/-     0.71)       41        0 (    5.57 +/-     4.98)
   4 NameSpaceURIKey             8       72      158        9 (    8.16 +/-     7.62)        0        0 (    0.00 +/-     0.00)
   5 nsSupportsArray            36    11304     2581      314 (  477.13 +/-   476.53)     9223      314 (  579.23 +/-   578.64)
   6 nsView                     96        0       57        0 (   27.64 +/-    26.98)        0        0 (    0.00 +/-     0.00)
   7 nsEnderDocumentObser       12        0        1        0 (    0.50 +/-     0.87)        1        0 (    0.50 +/-     0.87)
- Here's how you interpret the columns: - - Interesting things to look for: - - You can also dump out bloat statistics interactively by typing -about:bloat in the location bar, or by using the menu items under the -QA menu in debug builds. Note that you need to have the XPCOM_MEM_BLOAT_LOG -or XPCOM_MEM_LEAK_LOG envirionment variable defined first. You can also type - about:bloat?new - to get a log since the last time you called it, or -about:bloat?clear to clear the current set of statistics completely (use -this option with caution as it can result in what look like negative refcounts, -etc). Whenever these options are used, the log data is dumped to a file relative -to the program's directory: -
bloatlogs/all-1999-10-16-010302.txt        -(a complete log resulting from the about:bloat command)
-bloatlogs/new-1999-10-16-010423.txt     (an incremental -log resulting from the about:bloat?new command)
- -

Viewing, Sorting, and Comparing Bloat -Logs

- -

You can view one or more bloat logs -in your browser by running the following program:

- -
perl  -mozilla/tools/memory/bloattable.pl log1 log2 - ... logn > htmlfile
- -

This will produce an HTML file that -contains a table such as:

- -
- -

Byte Bloats

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameFileDate
blankblank.txtTue Aug 29 14:17:40 2000
mozillamozilla.txtTue Aug 29 14:18:42 2000
yahooyahoo.txtTue Aug 29 14:19:32 2000
netscapenetscape.txtTue Aug 29 14:20:14 2000
- -
- -

The numbers do not include malloc -'d data such as string contents.

- -

Click on a column heading to sort -by that column. Click on a class name to see details for that class.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Class NameInstance
-Size		Bytes allocatedBytes allocated but not freed
blankmozillayahoonetscapeTotalblankmozillayahoonetscapeTotal
TOTAL
-
-
-
-
-
- 		+1754408+432556+179828+4041842770976
nsStr20+6261600+3781900+1120920+179134012955760+222760+48760+13280+76160360960
nsHashKey8+610568+1842400+2457872+11345926045432+32000+536+568+121634320
nsTextTransformer548+8220+469088+1414936+1532756342500000000
nsStyleContextData736+259808+325312+489440+3385601413120+141312+220800-11040+94944446016
nsLineLayout1100+2200+225500+402600+562100119240000000
nsLocalFile424+558832+19928+1696+1272581728+72080+1272+424-42473352
-
- -

The first set of columns, Bytes -allocated, shows the amount of memory allocated for the first log file -(blank.txt), the difference between the first log file and the -second (mozilla.txt), the difference between the second log file - and the third (yahoo.txt), the difference between the third log -file and the fourth (netscape.txt), and the total amount of memory -allocated in the fourth log file. These columns provide an idea of how hard -the memory allocator has to work, but they do not indicate the size of the -working set.

- -

The second set of columns, Bytes -allocated but not freed, shows the net memory gain or loss by subtracting -the amount of memory freed from the amount allocated.

- -

The Show Objects and Show -References buttons show the same statistics but counting objects or AddRef'd -references rather than bytes.

- -

Comparing Bloat Logs

- You can also compare any two bloat logs (either those produced when the program -shuts down, or written to the bloatlogs directory) by running the following -program: -
perl mozilla/tools/tinderbox/bloatdiff.pl -<previous-log> <current-log>
- This will give you output of the form: - 
Bloat/Leak Delta Report
Current file:  dist/win32_D.OBJ/bin/bloatlogs/all-1999-10-22-133450.txt
Previous file: dist/win32_D.OBJ/bin/bloatlogs/all-1999-10-16-010302.txt
--------------------------------------------------------------------------
CLASS                     LEAKS       delta      BLOAT       delta
--------------------------------------------------------------------------
TOTAL                   6113530       2.79%   67064808       9.18%
StyleContextImpl         265440      81.19%     283584     -26.99%
CToken                   236500      17.32%     306676      20.64%
nsStr                    217760      14.94%    5817060       7.63%
nsXULAttribute           113048     -70.92%     113568     -71.16%
LiteralImpl               53280      26.62%      75840      19.40%
nsXULElement              51648       0.00%      51648       0.00%
nsProfile                 51224       0.00%      51224       0.00%
nsFrame                   47568     -26.15%      48096     -50.49%
CSSDeclarationImpl        42984       0.67%      43488       0.67%
-
- This "delta report" shows the leak offenders, sorted from most leaks to fewest. -The delta numbers show the percentage change between runs for the amount -of leaks and amount of bloat (negative numbers are -better!). The bloat number is a metric determined by multiplying the -total number of objects allocated of a given class by the class size. Note -that although this isn't necessarily the amount of memory consumed at any -given time, it does give an indication of how much memory we're consuming. -The more memory in general, the worse the performance and footprint. The -percentage 99999.99% will show up indicating an "infinite" amount of leakage. -This happens when something that didn't leak before is now leaking. -

Bloat Statistics on Tinderbox

- Each build rectangle on Tinderbox will soon be capable of displaying the -total leaks delta and bloat delta percentages from one build to the next. -Horray!
- 
-  -
- - - - - - - - -
 warren   L - C
-   L:-3 
- B:+21 
-
- -

Hmmm. Warren checked in and the -number of leaks went down by 3%. (Yes!) But the amount of bloat went up by -21%. (Ouch!) This probably should be investigated further. Sometimes bloat -can go up because new features were added that just take up more memory (or -if the set of test URLs were changed, and the activity is different from -last time), but in general we'd like to see both of these numbers continue -to go down. You can look at the end of the log (by clicking on the L) to -see the bloat statistics and delta report for a breakdown of what actually -happened.
-

-
-

2. Boehm -GC Leak Detector

- more...
- -
- -

3. Refcount Tracing

- -

Refcount tracing is used to capture stack traces of AddRef and -Release calls to use with the Refcount Balancer. It is best to set the -XPCOM_MEM_REFCNT_LOG environment variable to point to a file when using -it.

- -

See Refcount -Balancer for more information. Also see the tutorial on -finding leaks of XPCOM objects.

- -
-

4. -Trace Malloc

-TraceMalloc captures stack traces of all malloc, calloc -, realloc, and free calls (this currently covers all -operator new and delete calls in Mozilla, too).  To enable -TraceMalloc in your build, configure with --enable-trace-malloc.  Run -the resulting mozilla with --trace-malloc filename as an argument, -and a binary log of events and callsite relations will be written to filename -.  If filename is -, nothing is written, but the TraceMalloc -machinery keeps track of all live allocations, and builds its tree of callsites -to keep book on stack backtraces.
-
-Tools such as bloatblame (tools/trace-malloc/bloatblame.c) can be used to process - filename.  Try running -with the unified output format option, -u.  The output is a large HTML -file that hyperlinks ancestor and descendent libraries, classes, and functions -that call into one another, attributing malloc blame up and down each graph.  -Bloatblame accumulates allocation counts, and ignores free calls.
-
-If you run with --trace-malloc -, your code can call NS_TraceMallocDumpAllocations( -pathname) at opportune times, and a human-readable listing of the current -heap, including stack traces for every allocation, will be written to -pathname.  This file can be post-processed by tools in -mozilla/tools/trace-malloc as follows:
- -Also, your JavaScript can call the following DOM window methods:
- -See -nsTraceMalloc.h for detailed comments on the log file format.
-
-

5. Leaky

- -

Using this stuff with leaky

- First, setup these environment variables: -
setenv LD_PRELOAD ../lib/libleaky.so -(assumes you execute apprunner/viewer in the dist/bin directory)
-setenv LIBMALLOC_LOG 8 (tells leaky to log addref/release calls)
-setenv XPCOM_MEM_LEAKY_LOG 1 (use leaky)
-setenv XPCOM_MEM_LOG_CLASSES "a,b,c" (the list of types you care about)
- Then run the viewer or the apprunner and run your test. Then exit it. The -result will be some large file in your current directory called "malloc-log" -and a small file called "malloc-map". If these aren't there then somethings -wrong. -

If it works properly, then you -now have the tracing data for the problem you are chasing in malloc-log. -Use leaky to convert it to human readable form and debug away:

-
leaky -dRq <viewer|apprunner> -malloc-log > /tmp/log
- Leaky used to require c++filt, but now it does it itself. With the -R option, -leaky will only log the refcnts that actually leaked (those that didn't go -to zero). -

Leaky environment variables

- -
LD_PRELOAD -
Set this to the -pathname to libleaky.so if you are using leaky to track memory operations.
- LIBMALLOC_LOG -
Set this to "8" -to enable leaky to track addref/release calls that are logged by xpcom. Note -that you must set bit 8 in xpcomrefcnt to connect xpcom's tracing to leakys -tracing.
-
- -

Sample output

- Here is what you see when you enable some logging with XPCOM_MEM_LOG_CLASSES -set to something: 
nsWebShell      0x81189f8       Release 5
nsWebShell::Release(void)+0x59
nsCOMPtr<nsIContentViewerContainer>::~nsCOMPtr(void)+0x34
nsChannelListener::OnStartRequest(nsIChannel *, nsISupports *)+0x550
nsFileChannel::OnStartRequest(nsIChannel *, nsISupports *)+0x7b
nsOnStartRequestEvent::HandleEvent(void)+0x46
nsStreamListenerEvent::HandlePLEvent(PLEvent *)+0x62
PL_HandleEvent+0x57
PL_ProcessPendingEvents+0x90
nsEventQueueImpl::ProcessPendingEvents(void)+0x1d
nsAppShell::SetDispatchListener(nsDispatchListener *)+0x3e
gdk_get_show_events+0xbb
g_io_add_watch+0xaa
g_get_current_time+0x136
g_get_current_time+0x6f1
g_main_run+0x81
gtk_main+0xb9
nsAppShell::Run(void)+0x245
nsAppShell::Run(void)+0xc7a92ede
nsAppShell::Run(void)+0xc7a9317c
__libc_start_main+0xeb
- -

Here is what you see -when you use the leaky tool to dump out addref/release leaks:

-

addref     -082cccc8     0 00000001 --> CViewSourceHTML::AddRef(void) -CViewSourceHTML::QueryInterface(nsID &, void **) NS_NewViewSourceHTML(nsIDTD -**) .LM708 GetSharedObjects(void) nsParser::RegisterDTD(nsIDTD *) RDFXMLDataSourceImpl::Refresh(int) -nsChromeRegistry::InitRegistry(void) nsChromeProtocolHandler::NewChannel(char -*, nsIURI *, nsILoadGroup *, nsIEventSinkGetter *, nsIChannel **) nsIOService::NewChannelFromURI(char -*, nsIURI *, nsILoadGroup *, nsIEventSinkGetter *, nsIChannel **) NS_OpenURI(nsIChannel -**, nsIURI *, nsILoadGroup *, nsIEventSinkGetter *) NS_OpenURI(nsIInputStream -**, nsIURI *) CSSLoaderImpl::LoadSheet(URLKey &, SheetLoadData *) CSSLoaderImpl::LoadChildSheet(nsICSSStyleSheet -*, nsIURI *, nsString &, int, int) CSSParserImpl::ProcessImport(int &, -nsString &, nsString &) CSSParserImpl::ParseImportRule(int &) -CSSParserImpl::ParseAtRule(int &) CSSParserImpl::Parse(nsIUnicharInputStream -*, nsIURI *, nsICSSStyleSheet *&) CSSLoaderImpl::ParseSheet(nsIUnicharInputStream -*, SheetLoadData *, int &, nsICSSStyleSheet *&) CSSLoaderImpl::LoadAgentSheet(nsIURI -*, nsICSSStyleSheet *&, int &, void (*)(nsICSSStyleSheet *, void *), -void *) nsLayoutModule::Initialize(void) nsLayoutModule::GetClassObject(nsIComponentManager -*, nsID &, nsID &, void **) nsNativeComponentLoader::GetFactoryFromModule(nsDll -*, nsID &, nsIFactory **) nsNativeComponentLoader::GetFactory(nsID &, -char *, char *, nsIFactory **) .LM1381 nsComponentManagerImpl::FindFactory(nsID -&, nsIFactory **) nsComponentManagerImpl::CreateInstance(nsID &, nsISupports -*, nsID &, void **) nsComponentManager::CreateInstance(nsID &, nsISupports -*, nsID &, void **) RDFXMLDataSourceImpl::Refresh(int) nsChromeRegistry::InitRegistry(void) -nsChromeProtocolHandler::NewChannel(char *, nsIURI *, nsILoadGroup *, nsIEventSinkGetter -*, nsIChannel **) nsIOService::NewChannelFromURI(char *, nsIURI *, nsILoadGroup -*, nsIEventSinkGetter *, nsIChannel **) NS_OpenURI(nsIChannel **, nsIURI -*, nsILoadGroup *, nsIEventSinkGetter *) nsDocumentBindInfo::Bind(nsIURI *, -nsILoadGroup *, nsIInputStream *, unsigned short *) nsDocLoaderImpl::LoadDocument(nsIURI -*, char *, nsIContentViewerContainer *, nsIInputStream *, nsISupports *, unsigned -int, unsigned int, unsigned short *) nsWebShell::DoLoadURL(nsIURI *, char -*, nsIInputStream *, unsigned int, unsigned int, unsigned short *) nsWebShell::LoadURI(nsIURI -*, char *, nsIInputStream *, int, unsigned int, unsigned int, nsISupports -*, unsigned short *) nsWebShell::LoadURL(unsigned short *, char *, nsIInputStream -*, int, unsigned int, unsigned int, nsISupports *, unsigned short *) nsWebShell::LoadURL(unsigned -short *, nsIInputStream *, int, unsigned int, unsigned int, nsISupports *, -unsigned short *) nsWebShellWindow::Initialize(nsIWebShellWindow *, nsIAppShell -*, nsIURI *, int, int, nsIXULWindowCallbacks *, int, int, nsWidgetInitData -&) nsAppShellService::JustCreateTopWindow(nsIWebShellWindow *, nsIURI -*, int, int, unsigned int, nsIXULWindowCallbacks *, int, int, nsIWebShellWindow -**) nsAppShellService::CreateTopLevelWindow(nsIWebShellWindow *, nsIURI *, -int, int, unsigned int, nsIXULWindowCallbacks *, int, int, nsIWebShellWindow -**) OpenChromURL(char *, int, int) HandleBrowserStartup(nsICmdLineService -*, nsIPref *, int) DoCommandLines(nsICmdLineService *, int) main1(int, char -**) main __libc_start_main

-

-
-

-5. Purify

- more...
- -
-

How to build xpcom -with refcnt/memory logging

- Built into xpcom is the ability to support the debugging of memory leaks. -By default, an optimized build of xpcom has this disabled. Also by default, -the debug builds have the logging facilities enabled. You can control either -of these options by changing environment variables before you build mozilla: -
FORCE_BUILD_REFCNT_LOGGING
- -
-
If this -is defined then regardless of the type of build, refcnt logging (and related -memory debugging) will be enabled in the build.
- NO_BUILD_REFCNT_LOGGING -
If this -is defined then regardless of the type of build or of the setting of the -FORCE_BUILD_REFCNT_LOGGING, no refcnt logging will be enabled and no memory -debugging will be enabled. This variable overrides FORCE_BUILD_REFCNT_LOGGING.
-
- The remaining discussion assumes that one way or another that xpcom has been -built with refcnt/memory logging enabled. -

-How to instrument your objects for refcnt/memory logging

- First, if your object is an xpcom object and you use the NS_IMPL_ADDREF and -NS_IMPL_RELEASE (or a variation thereof) macro to implement your AddRef and -Release methods, then there is nothing you need do. By default, those macros -support refcnt logging directly. -

If your object -is not an xpcom object then some manual editing is in order. The following -sample code shows what must be done:

-
-MOZ_DECL_CTOR_COUNTER(MyType) -

MyType::MyType() -
- { -
-   -MOZ_COUNT_CTOR(MyType);
- } -

-

MyType::~MyType() -
- { -
-   -MOZ_COUNT_DTOR(MyType);
- }

-
- Now currently the MOZ_DECL_CTOR_COUNTER expands to nothing so your code will -compile if you forget to add it; however, we reserve the right to change -that so please put it in. -

What are -those macros doing for me anyway?

- -


- NS_IMPL_ADDREF - has this additional line in it:

-
-NS_LOG_ADDREF(this, mRefCnt, #_class, sizeof(*this));
- What this is doing is logging the addref call using xpcom's nsTraceRefcnt -class. The implementation of that macro is:
-  -
-#define NS_LOG_ADDREF(_p, _rc, _type, _size) \
-   -nsTraceRefcnt::LogAddRef((_p), (_rc), (_type), (PRUint32) (_size))
- Which as you can see just passes the buck to nsTraceRefcnt. nsTraceRefcnt -implements the logging support and will track addref/release/ctor/dtor calls -in a database that it builds up as the program is executing. In a similar -manner, NS_IMPL_RELEASE uses NS_LOG_RELEASE which uses nsTraceRefcnt::LogRelease. -

For the -MOZ_DECL_CTOR_COUNTER, MOZ_COUNT_CTOR and MOZ_COUNT_DTOR macros the expansion -boils down to calls to nsTraceRefcnt::LogCtor and nsTraceRefcnt::LogDtor calls. -Again, the type of the object is passed in as well as the sizeof of all the -data type.

-
-#define MOZ_COUNT_CTOR(_type)                                 -\
- -PR_BEGIN_MACRO                                                -\
- -  nsTraceRefcnt::LogCtor((void*)this, #_type, sizeof(*this)); \ -
- -PR_END_MACRO -

-#define MOZ_COUNT_DTOR(_type)                                 -\
- -PR_BEGIN_MACRO                                                -\
- -  nsTraceRefcnt::LogDtor((void*)this, #_type, sizeof(*this)); \ -
- -PR_END_MACRO

-
- - - diff --git a/xpcom/doc/ObjectModel.html b/xpcom/doc/ObjectModel.html deleted file mode 100644 index 396ac4ec7d71..000000000000 --- a/xpcom/doc/ObjectModel.html +++ /dev/null @@ -1,117 +0,0 @@ - - - - - - Gemini Object Model - - - -

-Gemini Object Model

-The gemini object model is a cross platform component object model modelled -after win32's IUnknown and COM. We do not support a C API to gemini at -this time. -

-nsID

-Like OSF's DCE, we use an "interface id" which is a unique identifer which -names the interface. The nsID and be used as a key into a cross platform -registry service to discover an implementation of an interface. Here is -the declaration of nsID: - -On windows, the "uuidgen" program (provided with Visual C++) can be used -to generate these identifiers. -

-nsISupports

-This is the base class for all component objects. Not all objects are component -objects; these rules apply to objects which expose an interface which is -shared across dll/exe boundaries. Here is nsISupports: - -The semantics of this interface are identical to win32's "COM" IUnknown -interface. In addition, the types are carefully mapped and the names are -the same so that if necessary we can "flip a switch" and have the windows -version (or any other platform that embraces COM) use the native COM IUnknown -without source code modification. -

-Factory Procedures

-Factory procedures use this design pattern - -The return value is a status value (see nsISupports.h for the legal return -values); the first argument is a pointer to a cell which will hold the -new instance pointer if the factory procedure succeeds. The second argument -is a pointer to a containing component object that wishes to aggregate -in the Foo object. This pointer will be null if no aggregation is requested. -If the factory procedure cannot support aggregation of the Foo type then -it fails and returns an error if aggregation is requested. - -

The following symbols are defined for standard error return values from -QueryInterface and from factory procedures: -

- -

-nsIFactory

-Factory classes should eventually replace factory procedures for major -classes. They provide an easy mechanism for placing code in DLLs. The nsIFactory -class is as follows: -
  - -This interface is again identical to the COM version. More on registering -factories shortly. -

-Error Handling

-Because no exceptions are returned, error handling is done in the traditional -"error status value" method. -

-Cross Platform Registry

-A cross platform registry was written for the SmartUpdate feature of Communicator. -We will investigate it's usefulness for our purposes. -

-Library Management

-NSPR 2.x provides the cross platform mechanism for loading and unloading -libraries, and run time linking. -
  - - diff --git a/xpcom/doc/README b/xpcom/doc/README new file mode 100644 index 000000000000..edef8772a368 --- /dev/null +++ b/xpcom/doc/README @@ -0,0 +1,8 @@ + + + READ ME + + + +

+XPCOM documentation can be found at - - - - - - TODO List for XPCOM - - - -

-

-TODO List for XPCOM

- -
Last updated: 25 March 1999 -
Suresh Duddi
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskPriorityOwnerMileStone complete/Status
Move xpcom from using NR_*() functions (modules/libreg) to nsIRegistry -(xpcom/src/nsRegistry.cpp) -
    -
  • -Mainly you want to change all the Platform*() functions in nsComponentManager.cpp
    • - -
  • -Now we open/close the registry all the time. I want to keep the registry -open all the time. That would get performance up.
    • - -
  • -Platform*() functions use the NR_*Raw() functions in some places. I wonder -if the nsRegistry has a equivalent. If not we need to create them.
    • -
-Mostly, there is equivalence between NR_*() calls and nsRegistry calls. 		P2Nick Ambrose <nicka87@hotmail.com>3/22/1999 started -
3/27/1999 Patch submitted -
3/30/1999 landing -
DONE
RegisterFactory() and RegisterComponent(..persist=0) ignoring CONTRACTID. -Needs Fix.P1Nick Ambrose <nicka87@hotmail.com>4/6/1999 started -
4/7/1999 Patch submitted -
4/12/1999 Patch Checked in -
DONE
Startup components: Some components need to be created at startup. -Have a framework for them.P1Suresh Duddi
nsIRegistry access via Javascript.P1IDL of nsIRegistry will fix this says John -Bandhauer
API changes: Remove all pathlist. XPCOM should support only -paths.P1Suresh Duddi4/2/1999 Checked in -
DONE
Fix xpcom from being initialized before main from static variables.P1Suresh Duddi3/22/1999 Started. -
- checked in a fixed xpcom initialization sequence. -
- Now got to fix all code statically calling it. I know Netlib does. -
- 4/1/1999 Fixed netlib on unix from static intialization. WIN is left.
Path handling: Use nsFileSpec instead of file path names. Char * pathnames -are not intl, and cannot be stored in the registry. Plus that wont support -mac aliases. -
    -
  • -Possibly move autoreg out of xpcom
    • -
-		P1Suresh Duddi -
Robert Churchill		3/24/1999 started -
Blocked on deciding which solution to pick.
Registry dump utility (regExport exists on windows) and about:registry -(or) better yet an rdf data source for the registry.P3Suresh Duddi4/5/1999 Fixed regExport to accurately dump the registry on win and -unix. -
- regExport needs to be compiled on the mac.
Replace use of nsVector (PL_Vector) with nsISupportsArrayP3
PATH argument to NSRegisterSelf() and NSUnregisterSelf() to be a nsISupportsP1
Code Cleanup: -
    -
  • -Registry path strings in nsComponentManager.cpp #defined
    • -
-		P3Nick Ambrose <nicka87@hotmail.com>4/1/1999 started -
4/5/1999 Patch submitted and checked in -
DONE
Performance -
    -
  • -Cache commonly used registry keys
    • -
-		P1Nick Ambrose <nicka87@hotmail.com>4/1/1999 started -
4/5/1999 Patch submitted and checked in -
DONE
Factories: Use previously created factories for object creation instead -of creating the factory everytime the object needs to be created. -
    -
  • -This is very tricky as the factory is owned by the component and when it -decides to unload itself on a CanUnload() call, the factory will be released. -Got to make sure that the component manager gets notified of this if it -caches the factory.
    • -
-		P2
nsIAllocator: wrap it in a static apiP2John Bandhauer3/31/1999 started -
4/2/1999 Check in -
DONE
- -

-Documentation on XPCOM

- - - -
- - diff --git a/xpcom/doc/c++tips.html b/xpcom/doc/c++tips.html deleted file mode 100644 index 163e77c8dd16..000000000000 --- a/xpcom/doc/c++tips.html +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - C++ Tips - - - -

-C++ Tips

-This is a compilation of tips on how to write cross-platform C++ code that -compiles everywhere. -

-General

- - - -

-Windows Compatability

- -

-Metroworks Compatability

- - - -

-G++ Compatability

- - - - - diff --git a/xpcom/doc/leaks.html b/xpcom/doc/leaks.html deleted file mode 100644 index 77919fd401a0..000000000000 --- a/xpcom/doc/leaks.html +++ /dev/null @@ -1,774 +0,0 @@ - - - - - - - Memory leaks fixing - - - -
-

-Memory leaks fixing effort -

- -

-Viewer

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ComponentLeaks fixing by...Status (nsIModule conversion)
bin/Components/
caps.dllrjcDONE
chardet.dllkippDONE
history.dlldpDONE
jsloader.dllkippDONE
lwbrk.dllkippDONE
necko.dllkippDONE
necko_resource.dllkippDONE
necko_file.dllkippDONE
nsgif.dllkippDONE
nslocale.dllcataDONE
mimetype.dllrjcDONE
oji.dllrjcDONE
profile.dlldpDONE
raptorhtml.dllkippDONE
raptorview.dlldpDONE (doesnt cache factory)
rdf.dllkippDONE
uconv.dllcataDONE
ucvlatin.dllcataDONE
ucharuti.dllftangDONE
xpc3250.dllkippDONE
xppref32.dlldpDONE 
bin/
jsdom.dll
raptorhtmlpars.dllvidurDONE
raptorgfxwin.dll
raptorweb.dll
raptorplugin.dll
raptorwidget.dll
- -

-Apprunner only

-  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ComponentLeaks fixing by...Status (nsIModule conversion)
addrbook.dllalecfDONE
bookmarks.dllrjcDONE
brprof.dllXXXrjc says: This should be removed from build. See bug # 13732
chrome.dllneetiDONE
cnvts.dllmorseDONE
cookie.dllneetiDONE
directory.dllrjcDONE
emitter.dllalecfDONE
ender.dllmorseDONE
eventloop.dllXXX - Don't do this
intlcmpt.dllcataDONE
jar50.dllneetiDONE
jsurl.dllmorseDONE
mime.dllmscottDONE
mork.dllbienvenuDONE
mozbrwsr.dllalecfDONE
mozfind.dllalecfDONE
mozucth.dllalecfDONE
mozxfer.dllalecfDONE
msgbase.dllputtermanDONE
msgcompo.dllalecfDONE
msgdb.dllbienvenuDONE
msgimap.dllmscottDONE
msglocal.dllmscottDONE
msgnews.dllalecfDONE
nativeapp.dllXXX - Don't do this
necko_about.dllkippDONE
necko_data.dllkippDONE
necko_ftp.dllkippDONE
necko_http.dllkippDONE
nsjpg.dllkippDONE
nspng.dllkippDONE
nsprefm.dllneetiDONE
nsxpi.dllneetiDONE
pics.dllneetiDONE
prefwind.dllalecfDONE
rdfdomds.dllneetiDONE
regviewer.dllneetiDONE
related.dllrjcDONE
sample.dll-sample- Don't do this one.
search.dllrjcDONE
stremcnv.dllmorseDONE
strres.dllcataDONE
txmgr.dllmorseDONE
txtsvc.dllmorseDONE
ucvcn.dllcataDONE
ucvja.dllcataDONE
ucvko.dllcataDONE
ucvtw.dllcataDONE
ucvtw2.dllcataDONE
vcard.dllXXX - Don't do this
wallet.dllneetiDONE
wlltvwrs.dllneetiDONE
xpctest.dllneetiDONE
xpiflash.dllneetiDONE
- -
  -

-How to fix leaks in a dll

- -

-Stage 1: nsIModule conversion

- -
    -
  1. -Convert dll to use nsIModule. Sample code is in  mozilla/xpcom/sample/nsSampleModule.cpp. -Things to watch out for:
    2. - -
      -
    1. -nsIModule::UnregisterSelf should not return an Error.
      2. - -
    2. -Cache factories created by modules in the module.
      3. -
    -The sample code does all this right. So sticking to closely is adviced.
- -

-Stage 2: Leak fixing (DONT -DO THIS NOW)

- -
    -
  1. -While in purify run bin/TestShutdown -on the dll. For this you will need to find a CID that the module implements. -Then invoke TestShutdown as
    2. - -
      TestShutdown {123d4-4908-490840-409850}
    - -
  2. -Make sure there are no leaks from the purify output.
    3. - -
    Use ns<dll>Module::Shutdown() to release any global memory that -is being leaked.
- -
-
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -
  - - diff --git a/xpcom/doc/nsIClassInfo-overview.html b/xpcom/doc/nsIClassInfo-overview.html deleted file mode 100644 index e0a13a146611..000000000000 --- a/xpcom/doc/nsIClassInfo-overview.html +++ /dev/null @@ -1,262 +0,0 @@ - - - - - - nsIClassInfo Overview - - - - - - - - - -

nsIClassInfo Overview

- Mike Shaver <shaver@mozilla.org - >
-      Last Modified: March 12, 2001
- -
-

Table of Contents

- - - -
-

What is nsIClassInfo?

- -

- nsIClassInfo is an interface that provides information -about a specific implementation class, to wit:

- - - -

How do I use it?

- -

To get the nsIClassInfo object for the implementation behind - a given interface, simply QueryInterface for the nsIClassInfo - interface:

- -
C++:
- nsCOMPtr<nsIClassInfo> info = do_QueryInterface(ifacePtr);
-
- JavaScript:
- var info = ifacePtr.QueryInterface(Components.interfaces.nsIClassInfo);
- -

It's important to note that this will usually return a singleton - object: there often exists only one nsIClassInfo implementation for -all implementations of a given class. This is very important, because it -means that you can't QueryInterface back to the original object, -no matter how hard you try.

- -

Doesn't that break the COM - QueryInterface rules?

- -

Quite. As discussed in - bug 67699, though, it's a reasonable concession to make in order -to avoid an additional vtbl entry on every class that wants to export - nsIClassInfo data.
-

- -

What are the "language - helpers" for?

- -

The language helpers are basically hooks for alternate language bindings -to use for providing language-specific wrapping and manipulation behaviour, -without adding code to every wrapped object.  In - bug 67669, jband tells us what XPConnect does with the language helpers:

- -
-

When wrapping an object xpconnect QIs the object for its classinfo -(say 'foo'). If it has seen that foo classinfo pointer before then it knows -that this object is a foo and it can reuse all the info is knows about foo -objects. If it has never seen foo it will gather info (such as the JS helper) -and remember that for future wrappings of foo objects.

-

Assuming that the foo helper tells xpconnect to not bother QI'ing -each foo instance for a per instance helper (or if the instances don't respond -to QI for the helper) then the same foo helper is used on all calls from -JS relating to the foo instances.

-

What you may be missing is that methods on the helper (nsIXPCScriptable -in the xpconnect case) *all* receive a pointer to the instance wrapper when -called. I.e. the helper methods have an explicit 'self' param. This allows -the helper to customize its response for each method call without requiring -a helper per instance.

-
- See bug 67699 - for more interesting discussion about pluggable language helpers and decoupling -them from specific wrapped classes. -

- -

That sounds useful. - How do I make it work with my code?

- -

Why, yes, it is useful. To provide nsIClassInfo - data for your class, you need to ensure that it returns an nsIClassInfo - -implementing object when it is QueryInterfaced for - nsIClassInfo . Simple enough, but it can be even simpler through - the use of a handful of helper macros/functions. Choose your own adventure:

- -

I'm writing C++ code, - and I use the generic factory and nsModuleComponentInfo.

- -

First, make sure that your class has the nsIClassInfo - helpers, by changing the NS_IMPL_ISUPPORTS line:

- -
NS_IMPL_ISUPPORTS2(nsSampleImpl, nsISample, nsIOther)
-
- -

becomes

- -
NS_IMPL_ISUPPORTS2_CI(nsSampleImpl, nsISample, nsIOther)
-
- -

This will provide an implementation of a helper function, named - nsSampleImpl_GetInterfacesHelper, which handles the processing - of nsIClassInfo::getInterfaces.

- -

Next, in your module code, use NS_DECL_CLASSINFO to - provide the rest of the per-class infrastructure (a global pointer into -which to stash the nsIClassInfo object, and an extern declaration - of the interfaces-helper, in case it's defined in another file):

- -
NS_DECL_CLASSINFO(nsSampleImpl)
-
- -

You'll need one of these lines for each nsIClassInfo - -supporting class represented in your nsModuleComponentInfo - array.

- -

Lastly, fill in the appropriate members of nsModuleComponentInfo - to wire everything up:

- -
static nsModuleComponentInfo components[] =
- {
-   {
-     "Sample Component", NS_SAMPLE_CID, NS_SAMPLE_CONTRACTID, -           
-     nsSampleImplConstructor,
-     nsSampleRegistrationProc,
-     nsSampleUnregistrationProc,
-     nsnull /* no factory destructor */,
-     NS_CI_INTERFACE_GETTER_NAME(nsSampleImpl),  - /* interface getter */
-     nsnull /* no language helper */,
-     &NS_CLASSINFO_NAME(nsSampleImpl),  - /* global class-info pointer */
-     0 /* no class flags */
-   }
- };
-
- -

If you want to add a callback which provides language-helper - objects, replace the last nsnull with your callback. See the - - nsIClassInfo IDL file for details on language helpers and -other esoterica.

-

Note: the details of these macros may change -slightly over the next week or so, as we refine a system for using table-driven -QI and sharing data between QI and the class-info calls.
-

- -

I'm writing - C++ code, and I use a custom factory or a singleton service object.

- -

You need some utility macros, don't ya?  We're working - on it.  (You should really use the generic factory and module, though.  - See - nsUConvModule.cpp for an example of how to use nsModuleComponentInfo - and the generic modules even when you have highly-custom registration -requirements.)

- -

I'm writing JS code.

- You poor thing. You suffer without even a GenericModule helper. We're - working on -that, too. -

What's "interface -flattening"?

- -

-

Interface flattening is a way to present multiple interfaces -of the same object to a language binding, without requiring explicit -QueryInterface calls.  Consider the following interfaces and -an object obj that implements both of them:

-
-

interface nsIFoo : nsISupports {
-     void fooMeth(in string message);
-};

-

interface nsIBar : nsISupports {
-     void barMeth(in PRUint32 meaning);
-};

-
-

You could use the following code to call both fooMeth and -barMeth without any QueryInterface:
-

-
obj.fooMeth("welcome to foo");
-obj.barMeth(42);
-

Pretty, no?  Pretty, yes.

-

There are also intricacies related to conflicting method -names and the difference between interface sets that are part of a contract's -promise and those which are simply artifacts of the implementation, but they're -beyond the scope of this overview.
-
-

- - diff --git a/xpcom/doc/xpcom-brownbag-1.html b/xpcom/doc/xpcom-brownbag-1.html deleted file mode 100644 index 72eef803a5ba..000000000000 --- a/xpcom/doc/xpcom-brownbag-1.html +++ /dev/null @@ -1,487 +0,0 @@ - - - - - - xpcom-review - - - -
-

-XPCOM Brown Bag I

- -
Suresh Duddi <dp@netscape.com> -
August 17, 1999  -
- -

-Terminology

-  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
InterfaceContract betwen the implementation and usage. A pure virtual abstract -base class with no data members. eg. nsIZip
IIDInterface ID {xxxxx-xxx-xxx-xxxxxx} a unique number that identifies -the Interface being talked about
nsISupportsThe mother of all interfaces. All interfaces ultimately inherit from -this. Provides refcounting. The IID and definition has been carefully choosen -so as to be binary compatible with COM.
ComponentAn implementation of a set of interfaces identified by a CLSID
ObjectAn instance of a Component
CLSIDComponent ID  {xxxxx-xxx-xxx-xxxxxx} a unique number that identifies -a component
ModuleA packaging of a set of Components (ie) a DLL
FactoryAn object whose sole purpose is creation of objects of a particular -component. There exists only one factory for every Component (CLSID). The -IID and definition has been carefully choosen so as to be binary compatible -with COM. nsIFactory
ClassObjectSame object as factory.
ContractIDA String name for a Component.
ComponentManagerCentral Object of XPCOM that provides API for object creation and management.
ServiceManagerA singleton manager. Holds and manages singleton references to objects -for application. Going to be merged with the componentmanager.
ServiceA singleton object within an application.
RegistryA hierarchical attribute-value pair storage.
XPIDLCross Platform Interface Definition Language. Language for expressing -interfaces.
TypelibA storage for meta information about interfaces. Interfaces expressed -in IDL have their meta information maintained in Typelib automatically.
XPConnectAbility to call c++ implementations of interfaces expressed in IDL -from javascript and viceversa.
- -

-An Interface

- - - -

-The Component

- - - -

-Object Creation

- - - -

-Object Release

- -
NS_IF_RELEASE(obj); -

It should be noted that release and addref are directly talking to the -object with no intermediaries. The macro NS_*_RELEASE() set the object -to NULL.

- -

-Component Registration Process

- - - - - -

-Module Unloading

- -
Every module implements a CanUnload() function that returns -a boolean of whether the module can be unloaded. This implies that the -module needs to be counting all outstanding object and return PR_TRUE only -if there are no outstanding objects served from within the module. -

Unloading happens either on a Timer or on an explicit call to nsComponentManager::FreeLibraries(). -The general logic is: -

-No assumptions can be made that the module will be unloaded if nsIModule::CanUnload() -returns PR_TRUE. It is guaranteed that if nsIModule::CanUnload() returns -PR_FALSE, the module will not be unloaded.
- -

-The Component Registry

- -
Nothing but a persistent hiearchical store of attribute value -pairs. It is the use of the registry by XPCOM that is very interesting. -Physical location of the registry is in the <exedir>/component.reg -

The xpcom hierarchy of the registry is considered to be opaque to components. -Use the nsIComponentManager Api to register as opposed to meddling with -the xpcom hierarchy in the registry directly. -

mozregistry.dat is NOT the component registry. It is the application -(apprunner) registry.

- -

-Old Method for Module definition

- -
Previously module definition was scattered across many exported -functions from a dll. -
 NSGetFactory( -), NSCanUnload( -), NSRegisterSelf( -), NSUnregisterSelf( -) -
Now these are combined into a nsIModule -

Please continue to use the old method until sample code using nsIModule -is available.

- -

-ComponentManager vs ServiceManager

- -
ServiceManager is a an object that holds instances to objects -in a cache and manages them. It uses the ComponentManager to create an -instance the first time an object is queried for. Lifetime of the instance -is currently the lifetime of the app. We are working on what is required -here and how to control the lifetime. Possbily merging ServiceManager with -the ComponentManager. -

From the components perspective there is nothing it does special to -behave as a service. The application controls the creation of services -by its usage or call to nsServiceManager::GetService() .Some components -that want to enforce being a service return cached instances on nsComponentManager::CreateInstance() -. -We are working on a more elegant syntax and semantics for this. Post suggestions -to newsgroup netscape.public.mozilla.xpcom (or Email mozilla-xpcom@mozilla.org) -with suggestions.

- -

-ContractID vs CLSID

- -
CLSID is a number identifying a specific implementation. -

ContractID is a like a pointer to a CLSID. It is an opaque string to xpcom.It -is used for two purposes. -

    -
  1. -Implementation independence for clients: @mozilla.org/registry;1
    2. - -
    The CLSID associating itself to a ContractID can be changed. Hence if a -new implementation with a new CLSID superceeds an older implementation, -the client wont be tied to the older implementation if it uses the ContractID. -
  2. -CLSID switching: @mozilla.org/image/decoder;1?type=image/gif
    3. - -
    A client wants to create different objects based on a switch (the mimetype -for the case of imagedecoders). A Contractid is formed with a concatenation -of a BASE_CONTRACTID and the switch (mimetype) and an instance of that created. -Components, when registering, associate their CLSID to specific contractids.
-NOTE: Only Clients that are adamant about the use of a specific implementation -need to create instances using CLSID. -

We encourage use of ContractID. This works well in the scriptable world -too. -

We are working on a ContractID syntax.

- -

-Steps for XPCOM Review

- -
    -
  1. -Know your interfaces and objects.
    2. - -
    List the objects your component is serving. List the interfaces that -it implements. -
  2. -List the objects that your component uses.
    3. - -
  3. -http://www.mozilla.org/scriptable/interface-rules-we-break.html
    4. - -
  4. -Do not switch over to using nsIModule yet. We will publish sample code -in a week with guidelines.
    5. - -
  5. -Use the above stated macros.
    6. - -
  6. -http://www.mozilla.org/projects/xpcom/ -- Watch for more documents here
    7. -
- -


-

-
  - - diff --git a/xpcom/doc/xpcom-code-faq.html b/xpcom/doc/xpcom-code-faq.html deleted file mode 100644 index ec48606b7da9..000000000000 --- a/xpcom/doc/xpcom-code-faq.html +++ /dev/null @@ -1,319 +0,0 @@ - - - - - - - XPCOM Code FAQ - - - -

-XPCOM Code FAQ

-Suresh Duddi <dp@netscape.com> -
Last Modified: May 25 2000 -
-
-
I am documenting things randomly as I am replying to people's questions. -So this looks more like an FAQ. -

-Table of Contents

- -
    -
  1. -What are the -Global Objects that XPCOM maintains
    2. - -
  2. -What are the -static classes that XPCOM maintains
    3. - -
  3. -Is -there any restriction on which static class I should call first
    4. - -
  4. -What -is the order of creation of the ServiceManager, ComponentManager and Registry
    5. - -
  5. -Is there a global -Registry being maintained
    6. - -
  6. -ComponentManager -Vs ServiceManager
    7. - -
  7. -ContractID Vs CLSID
    8. - -
  8. -How to set breakpoints -in component code
    9. - -
  9. -Generating the XPCOM LOG -
    10. -
- -

-What are -the Global Objects that XPCOM maintains

- - - -

-What are -the static classes that XPCOM maintains

- -
nsComponentManager -
nsServiceManager
- -

-Is -there any restriction on which static class I should call first

- -
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. -

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.

- -

-What -is the order of creation of the ServiceManager, ComponentManager and Registry

- -
Init_XPCOM() -
-
  • -create the global service manager
    • - -
  • -create the global component manager and register as service with the global -service manager
    • - -
  • -RegisterFactory(...RegistryFactory...)  Register the RegistryFactory -with the component manager so that new registry objects can be created.
    • -
    -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.
    - -

    -Is there a global -Registry being maintained

    - -
    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. -

    The ContractID for the registry will be @mozilla.org/registry;1 -
     

    - -

    -ComponentManager -Vs ServiceManager

    - -
    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. -

    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. -

    Client -

    -Component - -
    - -

    -ContractID Vs CLSID

    - -
    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} -

    ContractID is the string identification of an implementation of a component -the client is looking for. The representation takes a URI syntax. Eg. @mozilla.org/network/protocol;1?description=Http Protocol Handler&name=http -
    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). -

    Client -

    -Component - -
    - -

    -How to set break -points in component code

    - -
    -
    Since components are dynamically loaded only on demand, debugging -them could be a hard. Here are some tips to debugging components. -

    Windows: VC5.0 VC6.0 -

    Include your component library in the Project->Settings, Additional -Dll. drop down. After that breakpoints can be enabled.
    -Unix: gdb -
    -
      -
    • -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. - <Eric -Van Der Poel>
      • -
    - -
      -
    • -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. - <Alec -Flett>
      • -
    - -
      -
    • -Using XPCOM_BREAK_ON_LOAD environment variable:
      • - -


      gdb> set env XPCOM_BREAK_ON_LOAD "necko:rdf" -
      gdb> r -

      This will cause xpcom to break in the debugger after loading any dll -with substrings necko or rdf in them. At this point, -you could instruct the debugger to load the dll symbols and set breakpoint. -

      gdb> sha libnecko.so -
      gdb> b nsFunctionInNecko

    -
    -Mac: Codewarrior -
    Just open the appropriate .xSYM file in the debugger; the debugger -will target the library when the application is run. - <Simon -Fraser>
    -
    -
    -Generating a log from xpcom: -
    XPCOM provides log output. To enable the logging: -
    [unix] -
    setenv NSPR_LOG_MODULES nsComponentManager:5 -
    setenv NSPR_LOG_FILE xpcom.log -

    [win] -
    set NSPR_LOG_MODULES=nsComponentManager:5 -
    set NSPR_LOG_FILE=xpcom.log

    -Start your application after setting the above environment variables. Debug -log from xpcom would be in the file xpcom.log
    - -


    XPCOM Log analysis -

    xpcom/doc/xpcom-log-analyze.sh -is a script that does analysis of the xpcom log and prints out useful statistics -in html format. Usage is: -
    xpcom-log-analyze.sh < xpcom.log > xpcom-log.html -
     
    -
    - -
    - - diff --git a/xpcom/doc/xpcom-component-loaders.html b/xpcom/doc/xpcom-component-loaders.html deleted file mode 100644 index 66c3eb884a07..000000000000 --- a/xpcom/doc/xpcom-component-loaders.html +++ /dev/null @@ -1,143 +0,0 @@ - - - - - - - - -
    -

    -Component Loaders

    - -
    Brendan Eich <brendan@mozilla.org> -
    John Bandauer <jband@netscape.com> -
    Mike McCabe <mccabe@netscape.com> -
    Mike Shaver <shaver@mozilla.org> -
    Suresh Duddi <dp@netscape.com>
    - -

    -Scope of document

    - - - -

    -Why Component Loaders

    -Currently XPCOM requires all component to be packaged in DLLs and uses -the dynamic loading mechanism available with each platform to accomplish -instantiation of component. This method doesn't blend well with say components -written in java or javascript and packaged different from a DLL. Hence -the proposal for Component Loaders. -
      -

    -Component Loaders

    -XPCOM in its simplest form can be viewed as creating instances of objects -given a CONTRACTID or ClassID. How it does this instantiation is specific to -XPCOM and opaque to clients of XPCOM. -

    Internally XPCOM maps the passed in CONTRACTID to a CID and then the CID -maps into a DLL name. XPCOM loads the DLL assuming the dynamic loading -mechanism to create a factory. Then, asks the factory to create a particular -instance. Here are roughly the steps involved: -

      -
    1. -CreateInstance(..., CONTRACTID,...)
      2. - -
    2. -Map CONTRACTID to CID
      3. - -
    3. -Map CID to DLL
      4. - -
    4. -factory = Dynamically Load DLL to create Factory
      5. - -
    5. -Use Factory to create object instance
      6. -
    -The proposal for Component Loaders is to get XPCOM to delegate the loading -to a component loader: - - -

    -Autoregistration of non DLL Components and Component Loaders

    -<Need to figure this out> -
      -

    * -ContractID syntax might change -
    -

    -
    Last Modified: 1 Aug 1999  Suresh Duddi <dp@netscape.com> -
      - - diff --git a/xpcom/doc/xpcom-component-registration.html b/xpcom/doc/xpcom-component-registration.html deleted file mode 100644 index e28b320eda05..000000000000 --- a/xpcom/doc/xpcom-component-registration.html +++ /dev/null @@ -1,544 +0,0 @@ - - - - - - - XPCOM Dynamic Component Registration - - - -
    -

    -XPCOM Dynamic Component Registration

    - -
    Suresh Duddi <dp@netscape.com> -
    - -

    Dynamic object registration in XPCOM is achieved by interaction of the -following components: -

    -The registration mechanism for XPCOM components is similar in many ways -to that of COM. The XPCOM component dlls will have the opportunity to register -themselves with the registry. The exact time of installation would be either -at install time or as a result of autodetection by the Repository -Manager at runtime. -
    -
    -

    -The Component Registry

    -There are three types of Component Registries: -
      -
    1. -App-Component-Registry
      -      Each application has its own Component Registry that lives along with -the app in its <exe-dir>/components directory. The Component Registry -is created on installation or first run. It is be used read-only by XPCOM
      2. - -
    2. -User-Component-Registry
      3. - -
      Each user can install additional components under their user home directory. -These components will be shared across all XPCOM applications that the -user runs. -
    3. -Meta-Component-Registry
      4. - -
      Sharing Components between application: This can happen in two ways. -The installer of an application can find the other application's components -by looking for the application specifically and registering them with this -app's component registry. The second and more preferable approach is to -keep a machine wide Meta-Components-Registry that would aggregate all the -app component registries.
    -The difference component registries will be searched in the following order: -
      -
    1. -User Components Registry
      2. - -
    2. -App Component Registry
      3. - -
    3. -Meta Component Registry
      4. -
    -The user component registry is the only one that will be updated on the -fly by XPCOM. JS will be given the option to update either the App-Component-Registry -or the User-Component-Registry and this may succeed fail based on write -permission, although the general guideline is to update the User-Component-Registry. -JS will have to do special things to update the App-Component-Registry. -

    Profiles are a notion of the app (navigator) and xpcom has nothing to -do with it. The app will store app specific data in a Data-Registry that -will be stored under the user's home directory. -

    -How does this Solve our problems

    - -
      -
    1. -Multiple installations of mozilla and xpcom based apps
      2. - -
      Since each installation is going run with their own App-Component-Registry, -basically both apps will work. No inter process locking is essential. Since -both processes will operate on the User-Component-Registry, inter process -locking of the User-Component-Registry will be required. -
    2. -Third Party components installation
      3. - -
      Third parties can install components in their own directories and update -the App-Component-Registry (preferable) or User-Component-Registry depending -on if the sharing of component needs to be specific to the user or for -all users. Facilities for updating the registry would be to use JS or write -XPCOM code in their installer. The other option would be to add their components -in their own directory, create a App-Component-Registry of their own in -their directory and reference it in the Global Meta-Components-Registry. -This will get their components used by all applications. -
    3. -Registry used to store app specific data
      4. - -
      This is a totally separate registry: the Data-Registry. The theory -is that this will reside in the user's home directory. The registry hierarchy -is app specific. -
    4. -User Specific components
      5. - -
      This is basically the User-Component-Registry. Inter process locking -is required as all processes with XPCOM will access the same User-Component-Registry. -
    5. -Embedding
      6. - -
      This is requires more thought. The fact is when say Gecko is embedded -into an application, Gecko is running most probably in the process space -of that application and hence the XPCOM used will look for components in -this embedding applications directory. The embedding procedure should create -a App-Component-Reqistry for the embedding application that should contain -all the components from different apps this app would like to use. This -is however not required, if the Meta-Component-Registry exists. -
    6. -User not having permission to the place where the global registry lives, -if there is one.
      7. - -
      First the App-Component-Registry is written to only when there is a -new component or a component has gone away. New components come with installers -or the user calls regFactory.exe with the dll as an argument or clicks -on a button that says "refresh my user components" which will cause autoregistration -of user components. For deleted app components, annotations will be made -in the User-Component-Registry. Deleted user components is a non-issue. -
    7. -NFS mounted home directories and app directories
      8. - -
      NFS mounted home directories requires inter-machine locking of the -User-Component-Registry.  NFS mounted app directories dont have a -problem as the App-Component-Registry is  only used read-only by XPCOM.
    -So in summary, - -As a first cut, I am going to implement the App-Component-Registry for -M8. -

    -Hierarchy Used by Component Registry

    -XPCOM uses the nsRegistry to store mappings between CLSIDs and their implementations. -The Registry provides persistent storage of hierarchical keys and name-value -pairs associated with each key. Each key also keeps a default value. -

    XPCOM will use the following registry hierarchy: -

    ROOTKEY_COMMON -
        Common -
            Classes -
                -CLSID -
                 -{108d75a0-bab5-11d2-96c4-0060b0fb9956} -
                        -InprocServer (S)  = /home/dp/dist/bin/components/libnfs-protocol.so -
                        -ContractID       (S)  = @mozilla.org/network-protocol;1?type=nfs -
                        -ClassName    (S)  = NFS Protocol -Handler -

               @mozilla.org/network-protocol;1?type=nfs -
                    -CLSID        (S)  = {108d75a0-bab5-11d2-96c4-0060b0fb9956} -

        Software -
            Netscape -
                -XPCOM -
                    -VersionString          (S)  -= alpha0.20 -

                 -/home/dp/dist/bin/components/libnfs-protocol.so -
                        -ComponentsCount    (Int)  = 1 -
                        -FileSize           (Int)  -= 78965 -
                        -LastModTimeStamp   (S)    = Wed -Feb 24 11:24:06 PST 1999 -

                 -Events -
                        -Startup -
                         -{108d75a0-bab5-11d2-96c4-0060b0fb9956} -
                            -{17894983-ab78-8d75-a0bb-511d296c4006} -

                        -Shutdown -
                         -{748958ea-abab-511d-296c-40060b0fb995} -
                            -{45617894-983a-b788-d75a-0bab11d296c4} -
     

    - -

    - -
    The -Repository: Object instance creation

    -All object creation happens via The Repository.  nsIRepository::CreateInstance() -will be the primary way of creation of object instances. The steps in instantiation -of an object that implements the IID interface and of class CLSID is as -follows: -
      -
    1. -The CLSID of the component that would need to create the object instance -is identified.
      2. - -
        Callers use nsIRepository::ContractIDToCLSID() to convert the -ContractID string to the CLSID.
      - -
    2. -Load the dll associated with the CLSID after consulting the Registry
      3. - -
    3. -Instantiate the class factory by calling a globally exported dll function -NSGetFactory(). -This returns an instance of the class factory that implements the nsIFactory -interface.
      4. - -
    4. -The actual object creation is delegated to this nsIFactory instance -with a call to nsIFactory::CreateInstance().
      5. -
    - -

    - -
    The Service Manager

    -All globally created system services are available via the nsIServiceManager, -including the nsIRepository and nsIRegistry. Although -the nsIServiceManager uses the Registry and Repository in the -creation and maintenance of other services, the circular dependency is -broken by not letting the nsIServiceManager create the nsIRepository -and nsIRegistry instance and registering them specially with the -nsIServiceManager. -The nsIServiceManager is passed into NSGetFactory() for assisting the DLL -in the Factory creation process. -

    - -
    Component Registration

    -Either at installation time of the Component or at times when the XPCOM -library autodetect new/changed dlls, component registration is activated. -The autodetection happens at startup time of the navigator or via a javascript -trigger navigator.repository.autodetect(). The steps in component -registration would be: -
      -
    1. -The dll is loaded
      2. - -
    2. -The component is allowed to self register by a call to a globally exported -dll function NSRegisterSelf(). The nsIServiceManager -and the fullpath of the dll are passed in to assist in the registration -process. The dll is expected to create/modify its entries in the Registry -according to the guidelines of the XPCOM -hierarchy in the registry. nsIRepository, which can be queried -from the nsIServiceManager, has useful registration functions -that would easen the process.
      3. - -
    3. -The dll is unloaded
      4. -
    - -

    - -
    Autodetection -of Components

    -Autodetection of changed dlls happened by storing the dll's last modified -time and its size in the Registry automatically. If either the last modified -time stamp or the filesize differs from that stored in the Registry for -the dll, re-registration takes place. Before re-registration, the existing -instances of the objects created by the classes in the dll are not freed -because the nsIRepository has no list of them. The NSCanUnload() -will be called with input parameter force set to true. -The dll has to prepare for getting unloaded. After this call returns, the -dll will be unloaded if the return value is true. If the -dll detects that it cannot properly prepare for unloading, then it can -return false. XPCOM will not let the re-registration of the modified -dll proceed in this case. There is nothing much that XPCOM library can -do to salvage this situation other than warning the user of possible instability -and advice a restart upon which the re-registration will happen. -

    - -
    ContractID Spec

    -The general format of ContractIDs is @mozilla.org/compname&version?var=value&var=value&var=value... -

    Let us consider some more examples: -

      -
    1. -A pluggable protocol that implementes the nfs protocol
      2. - -
    2. -A converter that can handle application/x-zip
      3. - -
    3. -A plugin that can handle image/gif
      4. - -
    4. -A widget that can do a toolbar
      5. - -
    5. -A datasource that can handle mail
      6. - -
    6. -A helperapp that deals with application/postscript
      7. -
    -All the above have what type they are and one or more arguments on what -they particularly do. -

    The ContractID for these would look like -

      -
    1. -@mozilla.org/network-protocol;1?type=nfs
      2. - -
    2. -@mozilla.org/data-converter;1?type=application/x-zip
      3. - -
    3. -@mozilla.org/plugin;1?description=Renders GIF Images....&name=ImageMedia Gif Image Plugin&type=image/gif
      4. - -
    4. -@mozilla.org/widget;1?type=toolbar
      5. - -
    5. -@mozilla.org/rdf/datsource;1?type=mail
      6. - -
    6. -@mozilla.org/helperapp;1?type=application/postscript
      7. -
    -{Assume proper escaping of all above URI} -

    The above semantics would let ContractID be an extensible mechanism that -could be searched on multiple ways. And -
    query on a contractid should match only whatever was passed in. So a query -for -
    @mozilla.org/plugin;1?type=image/gif should pass for the contractid -specified above. We could extend this -
    mechanism with wildcards, but I dont want to go there yet... :-) -
      -

    - -
    Components created on -events

    -NOTE: THIS IS NOT BEING DONE. We are going to -expect the apps to this themselves by using the registry. -

    Some dlls have components that want to be created on certain events -namely Startup, Shutdown (for now). Example is xpinstall. -

    RegisterComponentForEvent(..., RegisterationTime when, ...) -
    RegisterFactoryForEvent(..., RegistrationTime when,...)
    -exists for this purpose. When an application wants to Fire the particular -event, it calls -
    nsComponentManager::FireEvent(RegistrationTime when)
    -ComponentManager will look for components that are registered to be created -on these events and do the following for each of the components: -
      -
    1. -CreateInstance(...,CID, knsIStartupComponentIID, &obj);
      2. - -
      For a shutdown event, knsIShutdownComponentIID would be used. -
        -
    2. -obj->Release();
      3. - -
      The component needs to take adequate measures to keep itself alive -and figure out how it would delete the object, since a Release() happens -immediately after a CreateInstace()
    -Warning: Order of creation of multiple components registered -on the same event is not defined. Component dependencies aren't thought -of yet. -
      -

    - -
    How will all this -help me

    -For Component Developers: - -For Component Users: -
    -
  • -No more hacking in calls to nsIRepository::RegisterFactory()
    • - -
  • -No need to know the CLSID of components that you want to instantiate. Component -creation can happen like this
    • - -
    nsIRepository::CreateInstance("@mozilla.org/network-protocol;1?type=nfs", -NULL, kProtocolIID, &result); -
    instead of -
    nsIRepository::CreateInstance(NFS_PROTOCOL_CID, NULL, domIID, -&result);
    - -

    - -
    What has happened -so far

    - - - -

    - -
    Changes to XPCOM -happening

    - - - -

    - -
    What should I do

    - - - -

    - -
    Issues

    - - - -
    -
    Last Modified: 28 Jan 1998 -
    Feedback to: netscape.public.mozilla.xpcom - - diff --git a/xpcom/doc/xpcom-log-analyze.pl b/xpcom/doc/xpcom-log-analyze.pl deleted file mode 100644 index 682ba0c930e2..000000000000 --- a/xpcom/doc/xpcom-log-analyze.pl +++ /dev/null @@ -1,208 +0,0 @@ -#!/usr/bin/perl - -# Perl script to analyze the log output from xpcom and print -# the results in html. -# -# To get the xpcom log output to a file say xpcom.log: -# setenv NSPR_LOG_MODULES nsComponentManager:5 -# setenv NSPR_LOG_FILE xpcom.log -# ./mozilla -# -# -# To get registry (used to figure out contractid mappings) -# ./regExport component.reg > registry.txt - -# Usage: -# -# a) To get simple output -# cat xpcom.log | perl xpcom-log-analyze.pl > xpcom-log.html -# -# b) To get all possible cid->contractid mappings filled in -# cat xpcom.log registry.txt | perl xpcom-log-analyze.pl > xpcom-log.html -# -# -# Author: Suresh Duddi -# Created Aug 9 2000 - -while (<>) -{ - chomp; - if ( /ContractIDToClassID.*\}/ ) - { - # Passed contractid to cid mapping. Add contractid to cid mapping - $cid = GetCID(); - $contractid = GetContractID(); - $contractid_map{$cid} = $contractid; - $contractid_passed{$contractid}++; - $ncontractid_passed++; - next; - } - - if ( /ContractIDToClassID.*FAILED/ ) - { - # Failed contractid. Collect it. - $contractid = GetContractID(); - $contractid_failed{$contractid}++; - $ncontractid_failed++; - next; - } - - if ( /CreateInstance.*succeeded/ ) - { - # Successful create instance - $objects{GetCID()}++; - $nobjects++; - next; - } - - if ( /CreateInstance.*FAILED/ ) - { - # Failed create instance - $objects_failed{GetCID()}++; - $nobjects_failed++; - next; - } - - if ( /: loading/ ) - { - $dll = GetDll(); - # make the name a little pretty - $dll =~ s/^.*bin\///; - $dll_loaded[@dll_loaded] = $dll; - next; - } - - if ( / classID - \{/ ) - { - # this is from the output of registry. Try to update contractid_map - $cid = GetCID(); - # Get the next contractid or classname line until a empty new line - $_ = until (/ContractID|ClassName/ || length == 1); - chomp; - $contractid = $_; - $contractid =~ s/^.*= //; - $contractid_map{$cid} = $contractid; - } -} - -PrintHTMLResults(); - - -sub GetContractID() { - # Get a proid from a line - my($contractid) = $_; - $contractid =~ s/^.*\((.*)\).*$/$1/; -# print "Got Progid: $contractid\n"; - return $contractid; -} - -sub GetCID() { - # Get a CID from a line - my($cid) = $_; - $cid =~ s/^.*\{(.*)\}.*$/$1/; -# print "Got cid: $cid\n"; - return $cid; -} - -sub GetDll() { - # Get a Dll from a line - my($dll) = $_; - $dll =~ s/^.*\"(.*)\".*$/$1/; -# print "Got dll: $dll\n"; - return $dll; -} - - -# -# Print the results of our log analysis in html -# -sub PrintHTMLResults() -{ - $now_time = localtime(); - print "XPCOM Log analysis dated: $now_time\n"; - print "\n"; - print "

    \n"; - print "XPCOM Log analysis dated: $now_time\n"; - print "

    \n"; -# ======================================================================== -# Performance analysis -# ======================================================================== - print "

    Performance Analysis

    \n"; - -# Number of dlls loaded - $n = @dll_loaded; - print "

    Dlls Loaded : $n

    \n"; - print "
    \n";
-    PrintArray(@dll_loaded);
-    print "
    \n"; - -# Objects created with a histogram - print "

    Objects created : $nobjects

    \n"; - print "
    \n";
-    @sorted_key = SortKeyByValue(%objects);
-    foreach $cid (@sorted_key)
-    {
-        printf("%5d %s [%s]\n", $objects{$cid}, $cid, $contractid_map{$cid});
-    }
-    print "
    \n"; - -# Passed contractid calls - print "

    Succeeded ContractIDToClassID() : $ncontractid_passed

    \n"; - print "
    \n";
-    @sorted_key = SortKeyByValue(%contractid_passed);
-    foreach $contractid (@sorted_key)
-    {
-        printf("%5d %s\n", $contractid_passed{$contractid}, $contractid);
-    }
-    print "
    \n"; - - -# ======================================================================== -# Error analysis -# ======================================================================== - print "

    Error Analysis

    \n"; - -# CreateInstance() FAILED - print "

    Failed CreateInstance() : $nobjects_failed

    \n"; - print "
    \n";
-    @sorted_key = SortKeyByValue(%objects_failed);
-    foreach $cid (@sorted_key)
-    {
-        printf("%5d %s [%s]\n", $objects_failed{$cid}, $cid, $contractid_map{$cid});
-    }
-    print "
    \n"; - -# ContractIDToClassID() FAILED with a histogram - print "

    Failed ContractIDToClassID() : $ncontractid_failed

    \n"; - print "
    \n";
-    @sorted_key = SortKeyByValue(%contractid_failed);
-    foreach $contractid (@sorted_key)
-    {
-        printf("%5d %s\n", $contractid_failed{$contractid}, $contractid);
-    }
-    print "
    \n"; - -# end the html listing - print "\n"; -} - - -sub PrintArray() -{ - my(@array) = @_; - for ($i=0; $i<@array; $i++) - { - print "$array[$i]\n"; - } -} - -# -# Sort a given hash by reverse numeric order of value -# return the sorted keylist -# -sub SortKeyByValue() -{ - my(%hash) = @_; - my(@sorted_keys) = sort { $hash{$b} <=> $hash{$a} } keys %hash; - return @sorted_keys; -} diff --git a/xpcom/doc/xpcom-log-analyze.sh b/xpcom/doc/xpcom-log-analyze.sh deleted file mode 100755 index 8e60286eeb51..000000000000 --- a/xpcom/doc/xpcom-log-analyze.sh +++ /dev/null @@ -1,105 +0,0 @@ -#!/bin/sh - -# -# Shell script to analyze the xpcom log file -# -# Usage: xpcom-log-analize.sh [] > xpcom-log.html -# -# You can generate the xpcom log file using: -# setenv NSPR_LOG_MODULES nsComponentManager:5 -# setenv NSPR_LOG_FILE xpcom.log -# ./mozilla -# -# -# Contributors: -# Suresh Duddi -# Vamsee Nalagandla -# - -if [ $# -gt 0 ] -then - logfile=$1 -else - logfile=xpcom.log -fi - -# make sure we got the logfile -if [ ! -f $logfile ] -then - echo "Error: Cannot find xpcom logfile $logfile" - exit -1 -fi - -echo "" -echo "" -echo "XPCOM Log analysis dated:" -date -echo "" -echo "

    " -echo "XPCOM Log analysis dated:" -date -echo "

    " -# ======================================================================== -# Performance analysis -# ======================================================================== -echo "

    Performance Analysis

    " - -# Number of dlls loaded -n=`grep -i ': loading' ${logfile} | wc -l` -echo "

    Dlls Loaded : $n

    " -echo "
    "
-grep ': loading' $logfile
-echo "
    " - -# Objects created with a histogram -n=`grep -i 'createinstance.*succeeded' ${logfile} | wc -l` -echo "

    Objects created : $n

    " -echo "
    "
-grep -i 'createinstance.*succeeded' ${logfile} | sort | uniq -c | sort -nr
-echo "
    " - -# Number of RegisterFactory -n=`grep 'RegisterFactory' $logfile | wc -l` -echo "

    Factory registrations : $n

    " -echo "
    "
-grep 'RegisterFactory' $logfile
-echo "
    " - -# Number of RegisterComponentCommon. -# XXX Order them by dllname -n=`grep 'RegisterComponentCommon({' $logfile | wc -l` -echo "

    Component Registrations : $n

    " -echo "
    "
-grep 'RegisterComponentCommon({' $logfile
-echo "
    " - -# Number of succeeded calls to ContractIDToClassID() with histogram -n=`grep -i 'contractidtoclassid.*}' $logfile | wc -l` -echo "

    Count of succeeded ContractIDToClassID() : $n

    " -echo "
    "
-grep -i 'contractidtoclassid.*}' $logfile | sort | uniq -c | sort -nr
-echo "
    " - - -# ======================================================================== -# Error analysis -# ======================================================================== -echo "

    Error Analysis

    " - -# CreateInstance() FAILED -n=`grep 'CreateInstance.*FAILED' $logfile | wc -l` -echo "

    Failed CreateInstance() : $n

    " -echo "
    "
-grep 'CreateInstance.*FAILED' $logfile
-echo "
    " - -# ContractIDToClassID() FAILED with a histogram -n=`grep 'ContractIDToClassID.*FAILED' $logfile | wc -l` -echo "

    Failed ContractIDToClassID() : $n

    " -echo "
    "
-grep 'ContractIDToClassID.*FAILED' $logfile | sort | uniq -c | sort -nr
-echo "
    " - -# -# Cleanup -echo "" diff --git a/xpcom/doc/xpcom-standalone.html b/xpcom/doc/xpcom-standalone.html deleted file mode 100644 index 5f7919595cf9..000000000000 --- a/xpcom/doc/xpcom-standalone.html +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - - - - -
    -

    -Standalone XPCOM v 0.5

    - -
    Version 0.5 -
    15 May 2000 -
    Suresh Duddi <dp@netscape.com> -
    - -

    -1.0  Overview

    -Standalone XPCOM is a tree configuration, that when built, provides a minimal -set of libraries (shared mostly) that can be used to get all features of -XPCOM. The contents of this standalone XPCOM in general are: -
      -
    • -NSPR : mozilla/nsprpub
      • - -
    • -Registry : mozilla/modules/libreg
      • - -
    • -XPCOM : mozilla/xpcom
      • -
    -NOTE 1: xpcom apis are not frozen yet. By XPCOM 1.0 release they will -be. -
    NOTE 2: xpcom standalone differs from the xpcom built with mozilla. -Hence cannot be used with the mozilla browser. -

    -2.0  Building Standalone XPCOM

    -Here are the instructions for building the Standalone XPCOM on Unix or Windows: -
      -
      Step 1 : Pull the sources -
    1. -cvs -z 3 co mozilla/client.mk
      2. - -
    2. -cd mozilla
      3. - -
    3. -gmake -f client.mk pull_all BUILD_MODULES=xpcom
      4. -
    - -
      Step 2 : Build XPCOM Standalone -
    1. -configure --enable-standalone-modules=xpcom
      2. - -
    2. -gmake
      3. -
    -

    -3.0  Testing Standalone XPCOM

    -xpcom/sample contains a sample application and a component. This -should get built by default. -
      -
    • -nsTestSample is the sample application. This should have been -installed in your bin/ directory.
      • - -
    • -libsample.so (unix) is the sample component implementation that -the sample application will try to instantiate. This should have been installed -in your bin/components directory
      • -
    -To run the test, -
      -
    1. -cd to your bin/ directory
      2. - -
    2. -setenv LD_LIBRARY_PATH .
      3. - -
    3. -./nsTestSample
      4. - -
      Warning: MOZILLA_FIVE_HOME not set. -
      nsNativeComponentLoader: autoregistering begins. -
      nsNativeComponentLoader: autoregistering succeeded -
      Inital print: initial value -
      Set value to: XPCOM defies gravity -
      Final print : XPCOM defies gravity -
      Test passed.
    - -

    -4.0  Test FAILED: What went wrong ?

    -The most common case of why the sample would have failed if you didn't -run it from the bin directory. Here are some error messsages and possible -ways of fixing them. -
      -
    1. -./nsTestSample: error in loading shared libraries: libxpcom.so: -cannot open shared object file: No such file or directory
      2. - -
        LD_LIBRARY_PATH not set. To fix "setenv LD_LIBRARY_PATH ."
      - -
    2. -Link errors when building xpcom standalone
      3. - -
        This is mostly due to the fact that probably xpcom is not being built -standalone. Make sure you did "configure --enable-standalone-modules=xpcom"
      -
    - -

    -5.0  Whats the difference between Standalone and non-Standalone XPCOM

    - - There is no binary difference between standalone XPCOM and the XPCOM that ships with the Mozilla browser. The one functional difference is that XPT files cannot be read from .zip files in standalone XPCOM. -

    -6.0  TODO for v 1.0

    - -
      -
    1. -Optional exclusion of specific features into standalone XPCOM like -registry, xpconnect. Tweeking these options will cause reduction -in memory requirements and size.
      2. - -
    2. -Get xpcom/tests directory upto date and documented.
      3. - -
    3. -Update this document for Mac.
      4. - -
    4. -API freeze and documentation
      5. -
    - -

    -7.0  Future (post v 1.0)

    -mmh! let me think... -

    -

    -
    Suresh Duddi <dp@netscape.com> - - diff --git a/xpcom/doc/xpcom_faq.html b/xpcom/doc/xpcom_faq.html deleted file mode 100644 index 5a0c976fad40..000000000000 --- a/xpcom/doc/xpcom_faq.html +++ /dev/null @@ -1,161 +0,0 @@ - - - - - - - xpCom FAQ - - -XPCOM FAQ -

    Get out your decoder rings kids! -

    Having a basic understanding of COM is only the first -
    step. To get CMonkey code to build and run, -
    you  need to translate your COM ideas into Netscape -
    speak. -

    Feel free to add to this document or change incorrect info. -
    Hopefully more info and more examples will help new -
    people reach XPCOM nirvana more quickly. -

    To mentally translate XPCOM to COM. -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    vanilla COMXPCOM
     IUnknownnsISupports
    IClassFactorynsIFactory
    virtual void _stdcallNS_IMETHOD
    interface ID = IIDnsID = nsIID = IID
    class ID = CLSID nsCID = CID
    - -

    Not too difficult. -
    But wait. There's more. -
    ------------------------------------------- -

    Why don't those classes have AddRef? -

    Actually, those classes do have AddRef. It is hidden -
    in a macro. There are alot of  macros that are alot of  help -
    once you know : -
        1) They exist. -

        2) Where they are defined. (They aren't always mnemonic -or onomatipeic. -
                -You might want to print them out.) -

                mozilla/xpcom/public/nsCom.h -
                -mozilla/xpcom/public/nsISupports.h -

        3)What they are -
                -Here's a short list to give you an idea of what you've been missing. -
                -The include files listed above are the real reference. -

        4) A quick way to expand pesky macros: -
                  -For macros in  foo.cpp,  'make foo.i' -

                This -will pump the foo.cpp file through C preprocessing -
                -and expand all the macros for you.  The output can be -
                -hard to read, but if you search for  unique strings -
                -in the area you aredebugging, you can navigate -
                -the file pretty easily. -
                -(thanks to hshaw@netscape.com) -
      -
      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Netscape MACROExpansion of macro
    NSADDREF(factoryinstname)Factory->AddRef();
    NS_IMETHODvirtual nsresult __stdcall
    NS_INIT_REFCNT()mRefCnt = 0
    NS_INIT_ISUPPORTS()NS_INIT_REFCNT()
    NS_DECL_ISUPPORTSpublic: -
              NS_IMETHOD QueryInterface(REFNSIID -aIID, -
                                -void** aInstancePtr); -
              NS_IMETHOD_(nsrefcnt) -AddRef(void); -
              NS_IMETHOD_(nsrefcnt) -Release(void); -
        protected: -
              nsrefcnt mRefCnt;
    - -

     Useful Links to COM Documents: -

    XPCOM  Page -
    nsCOMPtr -
    Coding -Conventions -
    Getting BAMmed -
    How to COM -
    Modularization -Techniques -
    C++ -Portability Guide -
    NGLayout -
      -
      -
      - -