[Python-checkins] CVS: python/dist/src/Modules socketmodule.h,1.3,1.4

2002年2月25日 06:45:42 -0800

Update of /cvsroot/python/python/dist/src/Modules
In directory usw-pr-cvs1:/tmp/cvs-serv7444
Modified Files:
	socketmodule.h 
Log Message:
Add documentation about how the inter-module linking works.
Index: socketmodule.h
===================================================================
RCS file: /cvsroot/python/python/dist/src/Modules/socketmodule.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** socketmodule.h	17 Feb 2002 04:13:21 -0000	1.3
--- socketmodule.h	25 Feb 2002 14:45:40 -0000	1.4
***************
*** 78,81 ****
--- 78,129 ----
 /* --- C API ----------------------------------------------------*/
 
+ /* Short explanation of what this C API export mechanism does
+ and how it works:
+ 
+ The _ssl module needs access to the type object defined in 
+ the _socket module. Since cross-DLL linking introduces a lot of
+ problems on many platforms, the "trick" is to wrap the
+ C API of a module in a struct which then gets exported to
+ other modules via a PyCObject.
+ 
+ The code in socketmodule.c defines this struct (which currently
+ only contains the type object reference, but could very
+ well also include other C APIs needed by other modules)
+ and exports it as PyCObject via the module dictionary
+ under the name "CAPI".
+ 
+ Other modules can now include the socketmodule.h file
+ which defines the needed C APIs to import and set up
+ a static copy of this struct in the importing module.
+ 
+ After initialization, the importing module can then
+ access the C APIs from the _socket module by simply
+ referring to the static struct, e.g.
+ 
+ Load _socket module and its C API; this sets up the global
+ PySocketModule:
+ 
+ 	if (PySocketModule_ImportModuleAndAPI())
+ 	 return;
+ 
+ 
+ Now use the C API as if it were defined in the using
+ module:
+ 
+ if (!PyArg_ParseTuple(args, "O!|zz:ssl",
+ 
+ 			 PySocketModule.Sock_Type,
+ 
+ 			 (PyObject*)&Sock,
+ 			 &key_file, &cert_file))
+ 	 return NULL;
+ 
+ Support could easily be extended to export more C APIs/symbols
+ this way. Currently, only the type object is exported, 
+ other candidates would be socket constructors and socket
+ access functions.
+ 
+ */
+ 
 /* C API for usage by other Python modules */
 typedef struct {
***************
*** 85,89 ****
 /* XXX The net effect of the following appears to be to define a function
 XXX named PySocketModule_APIObject in _ssl.c. It's unclear why it isn't
! XXX defined there directly. */
 #ifndef PySocket_BUILDING_SOCKET
 
--- 133,142 ----
 /* XXX The net effect of the following appears to be to define a function
 XXX named PySocketModule_APIObject in _ssl.c. It's unclear why it isn't
! XXX defined there directly. 
! 
! >>> It's defined here because other modules might also want to use
! >>> the C API.
! 
! */
 #ifndef PySocket_BUILDING_SOCKET