Changeset 1281 for trunk/doc/Fork.os2

Timestamp:

Mar 6, 2004, 10:48:26 PM (22 years ago)

Author:

bird

Message:

...

File:

• trunk/doc/Fork.os2 (modified) (11 diffs, 1 prop)

trunk/doc/Fork.os2

@@ -162 +162 @@
         3. Extended versions of some memory related OS/2 APIs must be implemented.
         
-The implemenetation will further make the following assumption about the
+The implementation will further make the following assumption about the
 operation of OS/2:
         1. DosExecPgm will not return till all DLLs are initated successfully.
-        
+        2. DosQueryMemState() is broken if more than one page is specified.
+       (no idea why/how/where it's broken, but testcase shows it is :/ )
 
         
@@ -171 +172 @@
 ---------------------------------
 
-The fork() implementation requires a method of telling the child process
+The fork() implementation requires a method  telling the child process
 that it's being forked and must take a very different startup route. For
-some other LIBC apis there is need for parent -> child and child -> parent
+some other LIBC apis there  need for parent -> child and child -> parent
 information exchange. More specifically, the inheritance of sockets,
 signals, the different scheduler actions of a posix_spawn[p]() call, and
 possibly some process group stuff related to posix_spawn too if we get it
 figured out eventually. All this was parent -> child during spawn/fork. A
-need exist also for child -> parent notification and possibly exchange for
+need  for child -> parent notification and possibly exchange for
 process termination. It might be necessary to reimplement the different
 wait apis and implement SIGCHLD, it's likely that those tasks will make
@@ -184 +185 @@
 
 The choice is now whether or not to make this shared process management
-specific to each LIBC version or try to make it survive normal LIBC updates.
-Making is specific have advantages in code size and memory footprint (no
-reserved field), however it have certain disadvantages when LIBC is updated.
-The other option is to use a named shared memory object, defining the
-content with reserved space for later extensions so several versions of
-LIBC with more or less features implemented can co use the memory space.
+specific to each LIBC version as a shared segement or try to make it
+survive normal LIBC updates. Making is specific have advantages in code
+size and memory footprint (no reserved fields), however it have certain
+disadvantages when LIBC is updated. The other option is to use a named
+shared memory object, defining the content with reserved space for later
+extensions so several versions of LIBC with more or less features
+implemented can co use the memory space.
 
 The latter option is prefered since it allows more applications to
@@ -196 +198 @@
 processes using multiple versions of LIBC.
 
-The shared memory must be named \SHAREMEM\INNOTEKLIBC.V01, the version
+The shared memory  be named \SHAREMEM\INNOTEKLIBC.V01, the version
 number being the one of the shared memory layout and contents, it will
 only be increased when incompatible changes are made.
 
-The shared memory will be protected by an standard OS/2 mutex semaphore.
-It will not use any fast R3 semaphore since the the usage frequency is low
-and the result of a messup may be disastrous. Care must be take for
+The shared memory ll be protected by an standard OS/2 mutex semaphore.
+It 
+and the result of a messup may be disastrous. Care must be take for
 avoiding creation races and owner died scenarios.
 
-The memory will have a fixed size, since adding segments is very hard.
+The memory ll have a fixed size, since adding segments is very hard.
 Thus the size must be large enough to cope with a great deal of
-processes, but bearing in mind that OS/2 normally doesn't support more
+processes,  bearing in mind that OS/2 normally doesn't support more
 than a 1000 processes, with a theoritical max of some 4000 (being the
 max thread count). A very simplistic allocation scheme will be
@@ -214 +216 @@
 lists a linked list based heap would do fine.
 
-The process blocks will be rounded up to in size adding a reasonable
+The process blocks ll be rounded up to in size adding a reasonable
 amount of space resevered for future extensions. Reserved space must be
 all zeroed.
 
-The fork() specific members of the process block will be a pointer to
+The fork() specific members of the process block ll be a pointer to
 the shared memory object for the fork operation (the fork handle) and
 list of forkable modules. The fork handle will it self contain
@@ -227 +229 @@
 the forking of each module. (more details in section 4.0)
 
-The parent will before spawn, fork and exec (essentially before DosExecPgm
+The parent ll before spawn, fork and exec (essentially before DosExecPgm
 or DosStartSession) create a process block for the child to be born and
-link it into an embryo list in the shared memory block. The child will
-find the process block by looking searching an embryo list using the
-parent pid as key. All DosExecPgm and DosStartSession calls are
-serialized within one LIBC version. (If some empty headed programmer
-manages to link together a program which may end up using two or more
-LIBC versions and having two or more thread doing DosExecPgm at the
-very same time, well then he really deserves what ever trouble he gets!
-At least don't blame me!)
-
-Process blocks will have to stay around after the process terminated
+link it into an embryo list in the shared memory block. The child shall
+find it's process block by searching the embryo list using the parent pid
+as key. All DosExecPgm and DosStartSession calls shall be serialized within
+one LIBC version. (If some empty headed programmer manages to link together
+a program which may end up using two or more LIBC versions and having two
+or more thread doing DosExecPgm at the very same time, well then he really
+deserves what ever trouble he gets! At least don't blame me!)
+
+Process blocks shall have to stay around after the process terminated
 (for child -> parent term exchange), a cleanup mechanism will be invoked
 whenever a free memory threshold is reached. All processes will register
@@ -250 +251 @@
 
 
-The implementation will be based on a fork handle and a set of primitives.
+The implementation  based on a fork handle and a set of primitives.
 The fork handle is a pointer to an shared memory object allocated for the
 occation and which will be freed before fork() returns. The primitives
@@ -261 +262 @@
 
 The support for fork() is an optional feature of LIBC. The default
-executable produced with LIBC and GCC will not be forkable. The fork
+executable produced with LIBC and GCC  not be forkable. The fork
 support will be based on registration of the DLLs and EXEs in their
 LIBC supplied startup code (crt0/dll0). A set of fork versions of these
-modules will be made.
+modules .
 
 The big differnece between the ordinary crt0/dll0 and the forkable
@@ -270 +271 @@
 handling of the return code of that call.
 
-The structure will contain these fields:
-        - chain pointer.
-        - data segment base address.
-        - data segment end address.
-        - fork callback function.
-        
-The fork callback function is called _atfork_callback, it takes the fork
+The fork module structure:
+    typedef struct __libc_ForkModule
+    {
+        /** Structure version. (Initially 'FMO1' as viewed in hex editor.) */
+        unsigned int    iMagic;
+        /** Fork callback function */
+        int           (*pfnAtFork)(__LIBC_FORKMODULE *pModule,
+            __LIBC_FORKHANDLE *pForkHandle, enum __LIBC_CALLBACKOPERATION enmOperation);
+        /** Pointer to the _CRT_FORK_PARENT1 set vector.
+         * It's formatted as {priority,callback}. */
+        void           *pvParentVector1;
+        /** Pointer to the _CRT_FORK_CHILD1 set vector.
+         * It's formatted as {priority,callback}. */
+        void           *pvChildVector1;
+        /** Data segment base address. */
+        void           *pvDataSegBase;
+        /** Data segment end address (exclusive). */
+        void           *pvDataSegEnd;
+        /** Reserved - must be zero. */
+        int             iReserved1;
+    } __LIBC_FORKMODULE, *__LIBC_PFORKMODULE; /* urg! conventions */
+
+
+The fork callback function which crt0/dll0 references when initializing
+the fork modules structure is called _atfork_callback. It takes the fork
 handle, module structure, and an operation enum as arguments. LIBC will
 contain a default implementation of _atfork_callback() which simply
-duplicates the data segment.
-
-The register call, __libc_ForkRegisterModule(), will return:
-        - 0 if normal process startup. no forking.
-        - 1 if fork() is in progress. The crt0/dll0 code will then
-          not call any standard initiation code, but let the
-          _atfork_callback() do all necessary stuff.
+duplicates the data segment, and processes the two set vectors
+(_CRT_FORK_*1).
+
+crt0/dll0 will register the fork module structure and detect a forked
+child by calling __libc_ForkRegisterModule().
+
+Prototypes:
+    /**
+     * Register a forkable module. Called by crt0 and dll0.
+     *
+     * The call links pModule into the list of forkable modules
+     * which is maintained in the process block.
+     *
+     * @returns 0 on normal process startup.
+     * @returns 1 on forked child process startup.
+     *          The caller should respond by not calling any _DLL_InitTerm
+     *          or similar constructs.
+     * @returns negative on failure.
+     *          The caller should return from the dll init returning FALSE
+     *          or DosExit in case of crt0. _atfork_callback() will take
+     *          care of necessary module initiation.
+     * @param   pModule     Pointer to the fork module structure for the
+     *                      module which is to registered.
+     */
+    int __libc_ForkRegisterModule(__LIBC_FORKMODULE *pModule);
+
+
+
 
 
@@ -292 +332 @@
 
 These primitives are provided by the fork implementation in the fork
-handle structure. We will define a set of these primitives now, if
-later new ones are added the users of these must check that they are
+handle structure. We 
+new ones are added the users of these must check that they are
 actually present.
 
@@ -347 +387 @@
          */
         int pfnFlush(__LIBC_FORKHANDLE *pForkHandle);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
         ...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+