int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void*), void *arg); |
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.
-
attr = variable containing the attributes of the created thread
-
Input parameter.
There are many different "kinds" of threads.
This variable determines which kind you want to create.
(It is a bit variable, each bit in this
variable denotes some property.
You set the specific bits using the
pthread_attr_init() to indicate what property
you wish in your thread)
See next item for more details
- 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 (the value must be an address of some variable)
- 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 !!!
Return value:
- 0 if successful
- If a non-zeror, there was an error. The vakue is in fact as error code. (see "man errno" for detail on how to get to the meaning of the error)
- The attributes for a newly created thread is defined by
the user using a special bit-variable
of the type "pthread_attr_t".
The following definition will define one such variable; and the name of our variable is "attr" (you can call the variable any name that you like):
pthread_attr_t attr;
- Once such "pthread_attr_t" variable is defined,
you must first reset all properties to their
default values
using the function "pthread_attr_init()":
pthread_attr_init(&attr);
- 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 priority value, 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)
- Changing the default values:
-
There is no need
to change MOST of the default values
(In fact, my examples always use the default values)
- If you have the need to change some value,
you must invoke
specific functions to
set parameters
in the attr variable (after clearing the bits):
- 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.
- Example: Changing the default STACKSIZE
- The only default value that you would
ever feel the need to change is: stacksize
The stack is used to store:
- local variables
- parameter variables
- You will need to increase the stack size
if the function
run by a thread uses:
- many local variables
- is recursive (because the function will create multiple copies of parameter and local variables !!!)
- many local variables
- How to set your own stacksize (workspace size) for your threads:
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
- The only default value that you would
ever feel the need to change is: stacksize
-
There is no need
to change MOST of the default values
- As many parallel applications often have interspersed
sequential and parallel steps, where the exection of
the sequential step must wait until all threads in the parallel
step has finished execution;
you often find that threads must sometimes WAIT
on each other.
- The crucial difference between joinable and
detached threads is precisely this wiating 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.
- 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....)
- 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 */ int param; /* --------------------------------------------------- Clear out thread attributes (use default values) --------------------------------------------------- */ if (pthread_attr_init(&attr) != 0) { perror("Problem: pthread_attr_init"); exit(1); } /* --------------------------------------------------------- Optionally, set thread attributes if needed (often not) --------------------------------------------------------- */ if ( pthread_attr_setstacksize(&attr, 10000000) != 0) { perror("Problem: pthread_attr_setstacksize"); exit(1); } param = some value....; /* -------------------------------------------------------------- Create thread (once created, thread starts running my_proc() -------------------------------------------------------------- */ if (pthread_create(&TID, &attr, my_proc, ¶m) != 0) { perror("Problem: pthread_create"); exit(1); }We must also provide a function for the thread to execute: void *my_proc((void *) x) <---- new thread will begin { execution with this function .... }
- The function executed
by a thread can have
one parameter
Multiple parameters:
- Multiple parameters can be passed by passing the address of a data structure as the parameter
- To accomodate
different types
of parameter, the
casting (type conversion)
operation is usually needed
- Example: passing an integer parameter to a thread
-
Example Program:
(Pass parameter to thread) ---
click here
- Compile with: CC -mt thread04.C
/* -------------------------------------------------------- Worker thread will receive an INTEGER input parameter -------------------------------------------------------- */ void *worker(void *arg) { int *p; // Pointer (reference, address) to an integer variable int x; // An integer variable p = (int *) arg; // Casting "(void *)" type to "(int *)" x = *p cout << "Hi, my input parameter is " << x << endl; return(NULL); /* Thread exits (dies) */ }/* -------------------------------------------------------- Main creates thread and passes param to new thread -------------------------------------------------------- */ int main(int argc, char *argv[]) { pthread_attr_t attr; pthread_t tid; int param; // Integer pthread_attr_init(&attr); param = 12345; pthread_create(&tid[i], &attr, worker, ¶m) }- Try changing the type from int
to float
- Only in main
- Only in worker
- In both main and worker
- You will see that they must agree !
-
Example Program:
(Pass parameter to thread) ---
click here
- You have seen it in some examples before, I just want to
spell out the effect of the function pthread_join()
explicitly.
- When a thread A calls the function
Thread A invokes: pthread_join(B, &status); B = ID of a thread status = variable to receive the exit state of thread.- The calling thread (A) is suspended
until the target thread (B) completes
The thread B completes if the function (that thread B executes) returns or thread B executes the pthread_exit() function
- Note that thread B must be JOINABLE
Example:
int main(int argc, char *argv[]) { int i, num_threads; thread_t tid[100]; /* Thread ID used for thread_join() */ int param[100]; /* used to store parameters for threads */ pthread_attr_t attr; pthread_attr_init(&attr); /* ----- Check command line ----- */ if ( argc != 2 ) { cout << "Usage: " << argv[0] << " Num_Threads" << endl; exit(1); } /* ----- Get number of intervals and number of threads ----- */ num_threads = atoi(argv[1]); /* ------ Create threads ------ */ for (i = 0; i < num_threads; i = i + 1) { param[i] = 1001 + i; if ( pthread_create(&tid[i], &attr, worker, ¶m[i]) != 0 ) { cout << "Cannot create thread" << endl; exit(1); } } /* ---------------------------------- Wait for ALL threads to finish ---------------------------------- */ for (i = 0; i < num_threads; i = i + 1) pthread_join(tid[i], NULL); }(See example program above (thread04.C))
- The calling thread (A) is suspended
until the target thread (B) completes