From 06e5f437d9343e6981f9b0939a483fa9b1e41150 Mon Sep 17 00:00:00 2001 From: Olaf Barthel Date: Sun, 27 Nov 2005 09:25:21 +0000 Subject: [PATCH] - Moved the thread-safe library documentation. - The malloc() in libunix.a now allocates four bytes of memory instead of just one for a request to allocate 0 bytes. git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@15069 87f5fb63-7c3d-0410-a384-fd976d0f7a62 --- documentation/README.html | 70 +++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 36 deletions(-) diff --git a/documentation/README.html b/documentation/README.html index c71866a..3bbad8d 100644 --- a/documentation/README.html +++ b/documentation/README.html @@ -57,41 +57,6 @@ when it starts up. This is controlled via the __stack_size variable (se

I added some amiga.lib and debug.lib functionality to the library, but don't count on it to be complete.

-

2.1 Thread-safety

- -

The library code is supposed to be thread-safe if built with the __THREAD_SAFE -preprocesssor symbold defined. Note that 'thread-safe' does not mean -'reentrant'. Multiple callers for certain library functions are permitted, but -not for all of them. For example, mkdtemp() is not thread-safe, and neither is -rand() or localtime(). But as per POSIX 1003.1c-1995 there are thread-safe -variants of rand() and localtime() called rand_r(), localtime_r(), and others.

- -

The use of the socket I/O functions is still problematic because the -underlying bsdsocket.library API is not supposed to be used by any process -other than the one that opened it. While one TCP/IP stack (my own "Roadshow") allows you -to share the library base among different processes, if so configured, it is the -exception. No other TCP/IP stack available for the Amiga robustly supports a similar -feature. If the TCP/IP stack supports this feature, then the global variable -__can_share_socket_library_base will be set to a non-zero value.

- -

Errors reported by the socket I/O functions which modify the global variables -errno and h_errno may be directed to call the __set_errno() -and __set_h_errno() functions instead if the TCP/IP stack supports this feature. The global -variable __thread_safe_errno_h_errno will be set to a non-zero value if it does.

- -

A much more serious problem resides with the exit(), abort(), -assert() and raise() functions, and the how SIGINT signal is -processed. In the thread-safe library only the main() function may directly -or indirectly call the exit() function. No child process may do so, since this -would wreck its stack context, crashing it instantly; the main program would be very -likely to crash, too, because exit() will clean up after all memory allocations -and files currently in use. Functions such as abort() and raise() may -call the exit() function indirectly. And the raise() function may -be invoked as part of the Control+C checking. You should make sure that the -signal handling does not affect any child processes. This can be done by replacing the -__check_abort() function or by disabling SIGINT processing altogether, -such as through a signal(SIGINT,SIG_IGN) call.

-

3. What does it not do?

This library is a departure from the typical 'C' runtime environments of the @@ -174,6 +139,39 @@ yet. All that the thread-safety tries to afford you is not to get into big troub if simultaneous and overlapping accesses to files, memory allocation and other resources are taking place.

+

The library code is supposed to be thread-safe if built with the __THREAD_SAFE +preprocesssor symbold defined. Note that 'thread-safe' does not mean +'reentrant'. Multiple callers for certain library functions are permitted, but +not for all of them. For example, mkdtemp() is not thread-safe, and neither is +rand() or localtime(). But as per POSIX 1003.1c-1995 there are thread-safe +variants of rand() and localtime() called rand_r(), localtime_r(), and others.

+ +

The use of the socket I/O functions is still problematic because the +underlying bsdsocket.library API is not supposed to be used by any process +other than the one that opened it. While one TCP/IP stack (my own "Roadshow") allows you +to share the library base among different processes, if so configured, it is the +exception. No other TCP/IP stack available for the Amiga robustly supports a similar +feature. If the TCP/IP stack supports this feature, then the global variable +__can_share_socket_library_base will be set to a non-zero value.

+ +

Errors reported by the socket I/O functions which modify the global variables +errno and h_errno may be directed to call the __set_errno() +and __set_h_errno() functions instead if the TCP/IP stack supports this feature. The global +variable __thread_safe_errno_h_errno will be set to a non-zero value if it does.

+ +

A much more serious problem resides with the exit(), abort(), +assert() and raise() functions, and the how SIGINT signal is +processed. In the thread-safe library only the main() function may directly +or indirectly call the exit() function. No child process may do so, since this +would wreck its stack context, crashing it instantly; the main program would be very +likely to crash, too, because exit() will clean up after all memory allocations +and files currently in use. Functions such as abort() and raise() may +call the exit() function indirectly. And the raise() function may +be invoked as part of the Control+C checking. You should make sure that the +signal handling does not affect any child processes. This can be done by replacing the +__check_abort() function or by disabling SIGINT processing altogether, +such as through a signal(SIGINT,SIG_IGN) call.

+

Also take care with file I/O involving the stdin/stdout/stderr streams; read/write operations on these streams will be mapped to the Input()/Output()/ErrorOutput() file handles of the process performing these operations. Since only this small set of @@ -352,7 +350,7 @@ character is accepted as an alternative to the period (.).

the global errno variable will be set to EINVAL.

In the libunix.a implementation a request to allocate -0 (zero) bytes will result in an allocation of at least 1 byte, which will +0 (zero) bytes will result in an allocation of at least 4 bytes, which will be set to zero. Each zero length allocation will return a different memory address.