- Method signature:
int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine, void*), void *arg);
Input Parameters:
-
attr = attributes of the created thread
-
Threads have a number of
properties.
This variable is used to specify thread properties
It is a bit variable: each bit in this variable denotes some property.
The property bits are set using the pthread_attr_init() function
-
start_routine = starting location of the execution of the new thread
(it is a function)
-
This is function that the new thread will execute
(but the execution need not be limited to just this
function, because a function can call other functions...)
The function can have one parameter (passed by reference) and can return a value
-
arg = argument for the start_routine function
-
This is parameter for the function start_routine
that the new thread will execute.
Remember that you must pass the address of the variable !!!
Output Parameters:
-
thread = thread ID.
-
Output only parameter.
Upon successful completion, pthread_create() stores the ID of the created thread in the location referenced by the variable thread.
Return value:
-
pthread_create()
returns
0
if
successful
-
pthread_create()
returns a
non-zero
error code
upon failre
(see "man errno" for detail on how to get to the meaning of the error)
-
attr = attributes of the created thread
- Example:
void *worker(void *arg) { ... computational routine... } pthread_t tid[100]; int main(int argc, char *argv[]) { int i, num_threads; ... for (i = 0; i < num_threads; i = i + 1) { if ( pthread_create(&tid[i], NULL, worker, NULL) != 0 ) { cout << "Cannot create thread " << i << endl; exit(1); } } } - NOTE: When thread attribute is NULL, a thread with default properties is created
- The thread attributes
are stored in a
bit-variable
of the
type pthread_attr_t
- Defining a thread attribute variable:
pthread_attr_t attr;
- You must first
reset all property bits
using the function
pthread_attr_init():
pthread_attr_init( &attr );
After initialization, you can now set the desired thread property using a number of set thread attribute functions
- The following is a list of "thread attributes" and
their default values
Attribute Default Meaning of default contentionscope PTHREAD_SCOPE_PROCESS Thread will compete for resources within the process detachstate PTHREAD_CREATE_JOINABLE Thread is joinable by other threads stackaddr NULL Workspace (stack) used by thread is allocated (reserved) by the operating system stacksize NULL Workspace size used by thread is determined by the operating system priority 0 Priority of the thread (the lower the higher the priority) policy SCHED_OTHER The scheduling policy is determined by the system inheritsched PTHREAD_EXPLICIT_SCHED scheduling policy and parameters are not inherited but explicitly defined by the attribute object guardsize PAGESIZE size of guard area for a thread's created stack (this area will help determine if the thread has exceeded the total amount of space that was allocated for the thread)
- Setting various thread attributes:
-
There is no need to change MOST of the default values
- To set
thread attributes,
the the following functions:
- pthread_attr_setscope(): change contentionscope
- pthread_attr_setdetachstate(): change detachstate
- pthread_attr_setstackaddr(): pick your own stack location
- pthread_attr_setstacksize(): pick your own stack size
- .. etc
- See: man pthread_attr_init for more functions.
- See: man pthread_attr_setscope for more details on the pthread_attr_setscope function, etc.
-
There is no need to change MOST of the default values
- Example: changing the default STACKSIZE
- When the
worker function
has a
large amount of local variables
(e.g., an array),
you may need to
increase the stacksize
- You also want a larger stack when the
worker function
is
recursive
- The stack is used to store:
- local variables
- parameter variables
- How to change the stacksize (workspace size) for a thread:
int pthread_attr_setstacksize( pthread_attr_t *attr, size_t stacksize );
Example:
pthread_attr_t attr; pthread_attr_init(&attr); pthread_attr_setstacksize(&attr, 10000000); // 10000000 bytes stack
- When the
worker function
has a
large amount of local variables
(e.g., an array),
you may need to
increase the stacksize
- A joinable thread
is a thread
that you can
wait for/upon
- Many parallel applications have
interspersed sequential and parallel steps:
set up data (sequential) computation on the data (parallel) gather result and set up new data (sequential) more computation on the data (parallel) ... and so on - The sequential step
must
wait
until
all threads in the preceeding parallel step
has finished their execution
Hence, threads must WAIT on each other.
- The crucial difference between joinable and
detached threads is precisely this waiting property
- Detached threads
run independently from other threads and
cannot wait for other threads.
The waiting on other threads is accomplished by using the function pthread_join() (more later).
- Joinable threads may call pthread_join() to wait on another thread.
- Detached threads
run independently from other threads and
cannot wait for other threads.
- The default value is joinable, you do NOT want to change this (unless you are going to provide some kind of barrier synchronization routine yourself....)
- A thread
A
can
wait on the termination
of another thread
B
using the
pthread_join()
function
- Syntax:
- thread = ID of the thread you are waiting for its termination
- status = updated by the terminating thread (can be used to return a status of a return value)
int pthread_join(pthread_t thread, void **status);
- Example:
pthread_t TID; int *out; pthread_create(&TID, NULL, my_proc, NULL); ... pthread_join(TID, (void **) &out); cout << "Output value = " << *out ;
void * my_proc(void * arg) { int output; output = 1234; pthread_exit( (void *) &output ); return(NULL); }
- Effect of
pthread_join() :
- The calling thread (main) is
suspended
until the target thread (TID)
completes
- The thread (TID) completes
if the function (that thread TID executes)
returns
or
the thread invokes the
function
pthread_exit()
- If the thread invokes the function pthread_exit() , it can return an address of a variable to pthread_join() (see example above)
- The calling thread (main) is
suspended
until the target thread (TID)
completes
- Example Program:
(Demo above code)
- Prog file: click here
Compile: CC -mt thread-join.C
- We can pass a parameter to a thread at thread creation:
- The address of the variable param is passed to the thread
extern "C" void * my_proc(void * input) { .... }
void main() { ... myType param; pthread_create(&TID, &attr, my_proc, (void *) ¶m) }
- Example: passing an integer to a thread
/* -------------------------------------------------------- Worker thread will receive an INTEGER input parameter -------------------------------------------------------- */ extern "C" void *worker(void * arg) { int * p; p = (int *) arg; // Convert back to the actual type cout << "Hi, my input parameter is " << *p << endl; return(NULL); /* Thread exits (dies) */ }
/* -------------------------------------------------------- Main creates thread and passes param to new thread -------------------------------------------------------- */ int main(int argc, char *argv[]) { pthread_t TID; int param; param = 12345; pthread_create(&TID, NULL, worker, ¶m) ^^^^^^ pass parameter }
- Example Program:
(Demo above code)
- Prog file: click here
Compile with: CC -mt thread04.C
- The following code fragment summarizes how to create a thread:
pthread_t TID; /* Thread ID - used for signaling */ pthread_attr_t attr; /* Thread attribute values for creation */ myType param; /* --------------------------------------------------- Clear out thread attributes (use default values) --------------------------------------------------- */ if (pthread_attr_init(&attr) != 0) { perror("Problem: pthread_attr_init"); exit(1); } /* --------------------------------------------------------- Set some thread attributes if needed --------------------------------------------------------- */ if ( pthread_attr_setstacksize(&attr, 10000000) != 0) { perror("Problem: pthread_attr_setstacksize"); exit(1); } initialzie param....; /* -------------------------------------------------------------- Create threads - this function will be called MANY times ! -------------------------------------------------------------- */ if (pthread_create(&TID, &attr, my_proc, ¶m) != 0) { perror("Problem: pthread_create"); exit(1); } /* -------------------------------------------------------------- Commonly used: pthread_create(&TID, NULL, my_proc, NULL) -------------------------------------------------------------- */ /* -------------------------------------------------------------- Wait for threads to complete their tasks... -------------------------------------------------------------- */ pthread_join( TID, (void **) output );We must also provide a function for the thread to execute: extern "C" void *my_proc((void *) arg) <-- new thread will begin { execution with this function .... myType *p; p = (myType *) arg; .... (do the job).... pthread_exit( (void *) & output ); return(NULL); }