dg_pthread_group_create(3T) DG/UX 5.4R3.00 dg_pthread_group_create(3T)
NAME
dgpthreadgroupcreate, - create an empty thread group
SYNOPSIS
#include <pthread.h>
int dgpthreadgroupcreate(dgpthreadgroupt *threadgroup,
dgpthreadgroupattrt *attr);
where:
threadgroup A pointer to a location in which to store the new
thread group ID
attr A pointer to a thread group attributes object, or NULL
DESCRIPTION
The dgpthreadgroupcreate() function creates an empty thread group
and returns the ID of the thread group in the location pointed to by
threadgroup. If attr is non-NULL, the thread group is created using
the initialized thread group attributes pointed to by attr. If attr
is NULL, the default attributes are used to create the thread group;
in particular, the new thread group inherits the scheduling
attributes of the caller's thread group. Upon successful return, the
thread group contains no threads.
An application can use thread groups to schedule together
computationally-related threads from the same process. DG/UX
attempts to run threads in the same thread group on CPUs that are
physically close together. This CPU affinity can greatly improve the
performance of an application, particularly on a machine with many
CPUs and multiple levels of caching. DG/UX also allows applications
to manually affine thread groups to specific CPUs, providing even
greater control. Refer to <sys/intd6pthread.h>, <sys/dgcpu.h>,
and dgcpusetaffinity(3T) for a more detailed discussion of thread
groups and CPU affinity.
A thread can be created in a thread group by specifying the thread
group ID as an attribute for newly created threads with
dgpthreadattrsetgroup(3T). Because a thread's group is just
another thread creation attribute, the initialization of this
attribute can be well-isolated in DG-specific application code.
Properly initialized thread attributes objects can be passed to
pthreadcreate(3T) in a portable way. On a DG/UX system, the
attributes objects may indicate that classes of threads are created
in certain thread groups for optimal CPU affinity; on other systems,
this performance advantage would not be applicable or would be
applied in a different way. However, most of the application code
would remain portable.
The caller may change the CPU affinity parameters of a thread group
by translating the thread group ID into an LWP group ID using
dgpthreadgroupgetlwpgroupid() and calling appropriate CPU
affinity related functions defined in <sys/dgcpu.h>.
If dgpthreadgroupcreate() fails, no new thread group is created,
Licensed material--property of copyright holder(s) 1
dg_pthread_group_create(3T) DG/UX 5.4R3.00 dg_pthread_group_create(3T)
and the contents of the location pointed to by threadgroup are
undefined.
A thread group is not destroyed and cleaned up until
dgpthreadgroupdestroy() is called on the thread group and the
thread group contains no active or undetached threads.
DIAGNOSTICS
Return Value
If successful, dgpthreadgroupcreate() returns 0, and sets the
value pointed to by threadgroup to the new thread group's ID.
Otherwise it returns -1 and sets errno to indicate the error.
Errors
For each of the following conditions, dgpthreadgroupcreate()
returns -1 and sets errno to the corresponding value:
[EINVAL] An invalid attributes object has been specified. This
occurs when DG/UX has detected that the attributes object
pointed to by attr has not been initialized by a previous
call to dgpthreadgroupattrinit() or has been corrupted.
[EINVAL] An invalid combination of values has been specified in the
attributes object pointed to by attr.
[EPERM] The caller does not have permission to create a thread
group with the attributes object pointed to by attr.
[EAGAIN] The system- or user-imposed limit on the number of thread
groups would be exceeded by this call.
[ENOMEM] Insufficient memory exists to create the thread grup, even
though the caller is allowed to create another thread
group.
SEE ALSO
dgpthreadgroupattrinit(3T),
dgpthreadgroupattrsetinheritsched(3T),
dgpthreadgroupattrsetsched(3T), dgpthreadgroupattrsetprio(3T),
dgpthreadgroupdestroy(3T), dgpthreadgroupself(3T),
dgpthreadgroupequal(3T), dgpthreadattrsetgroup(3T),
pthreadcreate(3T), dgcpusetaffinity(3T), threads(5).
NOTES
After the call to dgpthreadgroupcreate() completes, the attributes
pointed to by attr are no longer associated with the newly created
thread group. Conceptually, they are simply copied to the new thread
group.
DG/UX attempts to reuse thread groups and their corresponding thread
group ids. An application should not assume that all thread group
ids assigned to thread groups in the same process will be unique for
the life of the process. As soon as a thread group has been
destroyed and has no active or undetached threads, its resources and
Licensed material--property of copyright holder(s) 2
dg_pthread_group_create(3T) DG/UX 5.4R3.00 dg_pthread_group_create(3T)
ID are made available for reuse. Hence an application needs to be
especially careful about not using a thread group ID after that
thread group has been destroyed and cleaned up.
Once a thread is created in a thread group, its thread group
assignment cannot be changed.
When a process is created, it contains a single thread group, called
the Initial Thread Group. By default, all threads are created in
this Initial Thread Group. DG/UX will still try to keep these
threads affined to the same CPUs on the underlying machine.
Licensed material--property of copyright holder(s) 3