<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-1261F3A3-6F27-5A85-81FF-A6858F03F711" xml:lang="en"><title>Single
and Multiple Threads</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This section describes the threads used in C programs. </p>
<section id="GUID-1EF3A0B4-E737-4BAA-8F1A-10F8BB39B5F5"><title>Threads</title> <p>The POSIX interface is designed for a single
thread of execution within a process. Many aspects of this interface do not
apply to a typical Symbian program in which multiple threads of execution
share the same address space. For information about threads and processes,
see <xref href="GUID-BBBFC0AF-2E35-5F5C-A3A5-57C4196A6CDA.dita">Threads and processes</xref>. </p> <p>STDLIB
allows for multiple threads, but each thread owns its own instance of the <codeph>_reent</codeph> structure
which contains private data such as the thread's <codeph>errno</codeph> variable.
Each thread's STDIO <codeph>FILE</codeph> structures are completely separate
from other threads', even if those structures eventually share the same underlying
file descriptor. A consequence of this is that different threads will buffer
their output to <codeph>stdout</codeph> separately, even though the eventual
output will be combined together when the STDIO layer flushes the buffers
out to the corresponding file descriptor. </p> <p>It is unclear how some POSIX
functions should be used in a multiple thread environment. An example is the <codeph>exit()</codeph> function.
Although each thread should have separate <codeph>atexit()</codeph> processing,
which should include closing all open STDIO files, it is unclear whether closing
the STDIO file should also close the underlying descriptor. STDLIB's current
implementation is to close the files, as would be expected to happen in a
normal POSIX process. However, this implementation may be changed. Note that <codeph>exit()</codeph> does
not attempt to free memory which was obtained by <codeph>malloc()</codeph>. </p> <p>The
user of STDLIB can take control over thread termination by implementing <codeph>exit()</codeph>, <codeph>_exit()</codeph>, <codeph>abort()</codeph> and <codeph>_assert()</codeph> in their own program, so that all of the
user's own code which calls these functions will invoke the user's routines
instead of the STDLIB versions. A helper function, <codeph>_atexit_processing_r()</codeph>,
can be called from the user's version of <codeph>exit()</codeph> to do the
normal <codeph>atexit</codeph> processing, if desired. See <codeph>stdlib_r.h</codeph> for
details. </p> </section>
<section id="GUID-3E022252-3471-41AB-BE87-2690B6DA9374"><title>Single-threaded programs</title> <p>Simple C programs may
not need to support file descriptors shared between threads, or the execution
of sub-processes. Such programs may use the default implementation of STDLIB,
in which the library code opens files, sockets etc. in the context of the
calling thread, and provides a per-thread table of open file descriptors. </p> <p>Multiple
threads may still be used, but each thread's resources are private and cannot
be shared with other threads. For example, a <codeph>setenv()</codeph> call
in one thread will not be seen by a <codeph>getenv()</codeph> call in another
and each thread will have a separate console window (created on demand when
the console is first read from or written to). </p> </section>
<section id="GUID-19D6688E-F2B3-4AA1-89E5-7CA9FA72648B"><title>Multi-threaded programs; the CPosixServer</title> <p>More
complex programs may need to use process-wide resources. This is often true
of programs which assume the existence of support for multiple threads within
a POSIX process. To meet this requirement, STDLIB can operate in a mode in
which all shareable resources are owned by a single <codeph>CPosixServer</codeph> thread.
In this mode, library routines such as <codeph>open()</codeph>, <codeph>read()</codeph> and <codeph>write()</codeph> operate
by passing an appropriate request to the <codeph>CPosixServer</codeph>. </p> <p>The
program's mode of operation is determined when it first tries to use STDLIB's
services. If a <codeph>CPosixServer</codeph> is running for the Symbian platform
process, the thread will use it; otherwise the program will operate in the
single-threaded mode. </p> <p>The <codeph>CPosixServer</codeph> is a Symbian
platform active object, and can be started either in the context of an existing
active scheduler, or by spawning a separate thread to run an active scheduler.
The functions for doing this have a C++ interface, defined in <codeph>estlib.h</codeph>.
For more information on active objects, see <xref href="GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita">active
objects</xref>. </p> <p>Communication between <codeph>CPosixServer</codeph> s
is used to establish the POSIX process hierarchy and to communicate resources
from parent to child. Programs which require multiple processes must use the
multi-threaded mode of operation. </p> </section>
</conbody><related-links>
<link href="GUID-BBBFC0AF-2E35-5F5C-A3A5-57C4196A6CDA.dita"><linktext>Threads and
                processes</linktext></link>
<link href="GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita"><linktext>Active  
              objects</linktext></link>
</related-links></concept>