@@ -77,14 +77,67 @@ typedef struct {
7777
7878/* --- C API ----------------------------------------------------*/
7979
80+ /* Short explanation of what this C API export mechanism does
81+ and how it works:
82+
83+ The _ssl module needs access to the type object defined in
84+ the _socket module. Since cross-DLL linking introduces a lot of
85+ problems on many platforms, the "trick" is to wrap the
86+ C API of a module in a struct which then gets exported to
87+ other modules via a PyCObject.
88+
89+ The code in socketmodule.c defines this struct (which currently
90+ only contains the type object reference, but could very
91+ well also include other C APIs needed by other modules)
92+ and exports it as PyCObject via the module dictionary
93+ under the name "CAPI".
94+
95+ Other modules can now include the socketmodule.h file
96+ which defines the needed C APIs to import and set up
97+ a static copy of this struct in the importing module.
98+
99+ After initialization, the importing module can then
100+ access the C APIs from the _socket module by simply
101+ referring to the static struct, e.g.
102+
103+ Load _socket module and its C API; this sets up the global
104+ PySocketModule:
105+
106+ if (PySocketModule_ImportModuleAndAPI())
107+ return;
108+
109+
110+ Now use the C API as if it were defined in the using
111+ module:
112+
113+ if (!PyArg_ParseTuple(args, "O!|zz:ssl",
114+
115+ PySocketModule.Sock_Type,
116+
117+ (PyObject*)&Sock,
118+ &key_file, &cert_file))
119+ return NULL;
120+
121+ Support could easily be extended to export more C APIs/symbols
122+ this way. Currently, only the type object is exported,
123+ other candidates would be socket constructors and socket
124+ access functions.
125+
126+ */
127+
80128/* C API for usage by other Python modules */
81129typedef struct {
82130 PyTypeObject * Sock_Type ;
83131} PySocketModule_APIObject ;
84132
85133/* XXX The net effect of the following appears to be to define a function
86134 XXX named PySocketModule_APIObject in _ssl.c. It's unclear why it isn't
87- XXX defined there directly. */
135+ XXX defined there directly.
136+
137+ >>> It's defined here because other modules might also want to use
138+ >>> the C API.
139+
140+ */
88141#ifndef PySocket_BUILDING_SOCKET
89142
90143/* --- C API ----------------------------------------------------*/
0 commit comments