From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 Apr 2024 10:17:27 +0200 Subject: Adding upstream version 7.0.14-dfsg. Signed-off-by: Daniel Baumann --- src/libs/xpcom18a4/python/doc/architecture.html | 116 ++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 src/libs/xpcom18a4/python/doc/architecture.html (limited to 'src/libs/xpcom18a4/python/doc/architecture.html') diff --git a/src/libs/xpcom18a4/python/doc/architecture.html b/src/libs/xpcom18a4/python/doc/architecture.html new file mode 100644 index 00000000..d12a2a76 --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/architecture.html @@ -0,0 +1,116 @@ + + + + + + + +Architecture + + + + +

Python XPCOM Package Architecture

+

Architecture

+

Much of the design for the Python XPCOM Package has been borrowed from the Python MS-COM +extensions in win32com. Most of the major limitations and drawbacks in the win32com +design have been addressed, mainly "auto-wrapping" of +interface objects, which is not supported by win32com.

+

Like win32com, this architecture includes the concept of client COM and server +COM.

+

Client COM:

+ +

Server COM:

+ +

The XPConnect framework is very powerful, and far exceeds what COM's +IDispatch can offer.  Thus, we are able to get by with far fewer interfaces +supported in the C++ level, and defer most things to the Python code that uses +XPConnect.  As a result, the requirement for a huge number of interfaces to +exist in the .pyd does not exist.  There are, however, a number of +interfaces that do require native C++ support: these are interfaces +required to "boot" the XPConnect support (i.e., the interfaces that are +used to get information about interfaces), and also two gateways that need to +work without interface information available. This last requirement is +due to the XPCOM shutdown-ordering - it may be a bug, but is not an unreasonable +amount of code anyway.

+

Auto-wrapping of COM objects is supported by both client COM and +server COM. For client COM, auto-wrapping means that the +Python programmer always sees Python "component" objects, rather than +raw C++ interface objects; to the user, it all appears to "just +work".  This is a major source of frustration in the win32com +framework.

+

For server COM, auto-wrapping means that you can +pass Python instances wherever a COM object is expected. If the Python +instance supports COM interfaces, by virtue of having a _com_interfaces_ +attribute that lists the interface requested, it will be automatically wrapped +in the correct COM object. 

+

Error Handling: The C++ framework has good error handling support, +and uses the XPCOM console service to log debug messages, Python exceptions and +tracebacks.  win32com does not have good exception/traceback support +at the C++ level, mainly because COM does not define a service like +the console where debug messages can go.  This does mean that in Mozilla +release builds, these debug messages are likely to be lost, but the --console +command line option to a release Mozilla will get them back.  Therefore, +the other error-support utilities, such as the error callbacks made on the +policy object, may be used.

+

Component Loader, Modules and Factories:  XPCOM has the concept +of a component loader - a module used to load all components of a +particular type.  For example, the moz.jsloader.1 component loads all +the JavaScript components. Similarly, the moz.pyloader.1 +component loads all Python components.  However, unlike +JavaScript, the Python component loader is actually implemented in Python +itself! Since the Python component loader can not be used to load +itself, this component has some special code, pyloader.dll, to boot-strap itself.

+

This means is that all XPCOM components, including the Python loader itself and all +XPCOM module and factory interfaces, are implemented in +Python. There are no components or interfaces implemented purely in C++ +in this entire package!

+ + + + -- cgit v1.2.3