Xenomai API  2.6.3
Thread creation attributes.

Thread creation attributes. More...

Collaboration diagram for Thread creation attributes.:

Functions

int pthread_attr_init (pthread_attr_t *attr)
 Initialize a thread attributes object.
int pthread_attr_destroy (pthread_attr_t *attr)
 Destroy a thread attributes object.
int pthread_attr_getdetachstate (const pthread_attr_t *attr, int *detachstate)
 Get detachstate attribute.
int pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
 Set detachstate attribute.
int pthread_attr_getstacksize (const pthread_attr_t *attr, size_t *stacksize)
 Get stacksize attribute.
int pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
 Set stacksize attribute.
int pthread_attr_getinheritsched (const pthread_attr_t *attr, int *inheritsched)
 Get inheritsched attribute.
int pthread_attr_setinheritsched (pthread_attr_t *attr, int inheritsched)
 Set inheritsched attribute.
int pthread_attr_getschedpolicy (const pthread_attr_t *attr, int *policy)
 Get schedpolicy attribute.
int pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy)
 Set schedpolicy attribute.
int pthread_attr_getschedparam (const pthread_attr_t *attr, struct sched_param *par)
 Get schedparam attribute.
int pthread_attr_getschedparam_ex (const pthread_attr_t *attr, struct sched_param_ex *par)
 Get schedparam_ex extended attribute.
int pthread_attr_setschedparam (pthread_attr_t *attr, const struct sched_param *par)
 Set schedparam attribute.
int pthread_attr_setschedparam_ex (pthread_attr_t *attr, const struct sched_param_ex *par)
 Set extended schedparam_ex attribute.
int pthread_attr_getscope (const pthread_attr_t *attr, int *scope)
 Get contention scope attribute.
int pthread_attr_setscope (pthread_attr_t *attr, int scope)
 Set contention scope attribute.
int pthread_attr_getname_np (const pthread_attr_t *attr, const char **name)
 Get name attribute.
int pthread_attr_setname_np (pthread_attr_t *attr, const char *name)
 Set name attribute.
int pthread_attr_getfp_np (const pthread_attr_t *attr, int *fp)
 Get the floating point attribute.
int pthread_attr_setfp_np (pthread_attr_t *attr, int fp)
 Set the floating point attribute.
int pthread_attr_getaffinity_np (const pthread_attr_t *attr, xnarch_cpumask_t *mask)
 Get the processor affinity attribute.
int pthread_attr_setaffinity_np (pthread_attr_t *attr, xnarch_cpumask_t mask)
 Set the processor affinity attribute.

Detailed Description

Thread creation attributes.

The services described in this section allow to set the attributes of a pthread_attr_t object, passed to the pthread_create() service in order to set the attributes of a created thread.

A pthread_attr_t object has to be initialized with pthread_attr_init() first, which sets attributes to their default values, i.e. in kernel-space:

In user-space, the attributes and their defaults values are those documented by the underlying threading library (LinuxThreads or NPTL).

Function Documentation

int pthread_attr_destroy ( pthread_attr_t *  attr)

Destroy a thread attributes object.

This service invalidates the attribute object pointed to by attr. The object becomes invalid for all services (they all return EINVAL) except pthread_attr_init().

See Also
Specification.
int pthread_attr_getaffinity_np ( const pthread_attr_t *  attr,
xnarch_cpumask_t *  mask 
)

Get the processor affinity attribute.

This service stores, at the address mask, the value of the affinity attribute in the attribute object attr.

The affinity attributes is a bitmask where bits set indicate processor where a thread created with the attribute attr may run. The least significant bit corresponds to the first logical processor.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
maskaddress where the value of the affinity attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_getdetachstate ( const pthread_attr_t *  attr,
int *  detachstate 
)

Get detachstate attribute.

This service returns, at the address detachstate, the value of the detachstate attribute in the thread attribute object attr.

Valid values of this attribute are PTHREAD_CREATE_JOINABLE and PTHREAD_CREATE_DETACHED. A detached thread is a thread which control block is automatically reclaimed when it terminates. The control block of a joinable thread, on the other hand, is only reclaimed when joined with the service pthread_join().

A thread that was created joinable may be detached after creation by using the pthread_detach() service.

Parameters
attrattribute object
detachstateaddress where the value of the detachstate attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid;
See Also
Specification.
int pthread_attr_getfp_np ( const pthread_attr_t *  attr,
int *  fp 
)

Get the floating point attribute.

This service returns, at the address fp, the value of the fp attribute in the attribute object attr.

The fp attribute is a boolean attribute indicating whether a thread created with the attribute attr may use floating-point hardware.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
fpaddress where the value of the fp attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_getinheritsched ( const pthread_attr_t *  attr,
int *  inheritsched 
)

Get inheritsched attribute.

This service returns at the address inheritsched the value of the inheritsched attribute in the attribute object attr.

Threads created with this attribute set to PTHREAD_INHERIT_SCHED will use the same scheduling policy and priority as the thread calling pthread_create(). Threads created with this attribute set to PTHREAD_EXPLICIT_SCHED will use the value of the schedpolicy attribute as scheduling policy, and the value of the schedparam attribute as scheduling priority.

Parameters
attrattribute object;
inheritschedaddress where the value of the inheritsched attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_getname_np ( const pthread_attr_t *  attr,
const char **  name 
)

Get name attribute.

This service stores, at the address name, the value of the name attribute in the attribute object attr.

The name attribute is the name under which a thread created with the attribute object attr will appear under /proc/xenomai/sched.

The name returned by this function is only valid until the name is changed with pthread_attr_setname_np() or the attr object is destroyed with pthread_attr_destroy().

If name is NULL, a unique default name will be used.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
nameaddress where the value of the name attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_getschedparam ( const pthread_attr_t *  attr,
struct sched_param *  par 
)

Get schedparam attribute.

This service stores, at the address par, the limited form of the schedparam attribute in the attribute object attr.

The limited form only defines the sched_priority member, that is sufficent to hold the scheduling parameter for SCHED_FIFO, SCHED_RR and SCHED_OTHER class members. Threads created with attr will use the value of this attribute as a scheduling priority if the attribute inheritsched is set to PTHREAD_EXPLICIT_SCHED. Valid priorities range from 1 to 99.

pthread_attr_getschedparam_ex() should be used to retrieve the parameters for extended scheduling classes, such as SCHED_SPORADIC or SCHED_TP.

Parameters
attrattribute object;
paraddress where the value of the schedparam attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_getschedparam_ex ( const pthread_attr_t *  attr,
struct sched_param_ex *  par 
)

Get schedparam_ex extended attribute.

This service is an extended version of pthread_attr_getschedparam(), that also supports Xenomai-specific or additional POSIX scheduling policies, which are not available with the host Linux environment.

Typically, SCHED_SPORADIC or SCHED_TP parameters can be retrieved from this call.

Parameters
attrattribute object;
paraddress where the value of the extended schedparam_ex attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_getschedpolicy ( const pthread_attr_t *  attr,
int *  policy 
)

Get schedpolicy attribute.

This service stores, at the address policy, the value of the policy attribute in the attribute object attr.

Threads created with the attribute object attr use the value of this attribute as scheduling policy if the inheritsched attribute is set to PTHREAD_EXPLICIT_SCHED. The value of this attribute is one of SCHED_FIFO, SCHED_RR, SCHED_SPORADIC, SCHED_TP or SCHED_OTHER.

Parameters
attrattribute object;
policyaddress where the value of the policy attribute in the attribute object attr will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_getscope ( const pthread_attr_t *  attr,
int *  scope 
)

Get contention scope attribute.

This service stores, at the address scope, the value of the scope attribute in the attribute object attr.

The scope attribute represents the scheduling contention scope of threads created with the attribute object attr. This implementation only supports the value PTHREAD_SCOPE_SYSTEM.

Parameters
attrattribute object;
scopeaddress where the value of the scope attribute will be stored on sucess.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_getstacksize ( const pthread_attr_t *  attr,
size_t *  stacksize 
)

Get stacksize attribute.

This service stores, at the address stacksize, the value of the stacksize attribute in the attribute object attr.

The stacksize attribute is used as the stack size of the threads created using the attribute object attr.

Parameters
attrattribute object;
stacksizeaddress where the value of the stacksize attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_init ( pthread_attr_t *  attr)

Initialize a thread attributes object.

This service initializes the thread creation attributes structure pointed to by attr. Attributes are set to their default values (see Thread creation attributes.).

If this service is called specifying a thread attributes object that was already initialized, the attributes object is reinitialized.

Parameters
attraddress of the thread attributes object to initialize.
Returns
0.
See Also
Specification.

Referenced by rt_task_create().

int pthread_attr_setaffinity_np ( pthread_attr_t *  attr,
xnarch_cpumask_t  mask 
)

Set the processor affinity attribute.

This service sets to mask, the value of the affinity attribute in the attribute object attr.

The affinity attributes is a bitmask where bits set indicate processor where a thread created with the attribute attr may run. The least significant bit corresponds to the first logical processor.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
maskaddress where the value of the affinity attribute will be stored on success.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_setdetachstate ( pthread_attr_t *  attr,
int  detachstate 
)

Set detachstate attribute.

This service sets to detachstate the value of the detachstate attribute in the attribute object attr.

Valid values of this attribute are PTHREAD_CREATE_JOINABLE and PTHREAD_CREATE_DETACHED. A detached thread is a thread which control block is automatically reclaimed when it terminates. The control block of a joinable thread, on the other hand, is only reclaimed when joined with the service pthread_join().

A thread that was created joinable may be detached after creation by using the pthread_detach() service.

Parameters
attrattribute object;
detachstatevalue of the detachstate attribute.
Returns
0 on success;
an error number if:
  • EINVAL, the attribute object attr is invalid
See Also
Specification.

Referenced by rt_task_create().

int pthread_attr_setfp_np ( pthread_attr_t *  attr,
int  fp 
)

Set the floating point attribute.

This service set to fp, the value of the fp attribute in the attribute object attr.

The fp attribute is a boolean attribute indicating whether a thread created with the attribute attr may use floating-point hardware.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
fpvalue of the fp attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_setinheritsched ( pthread_attr_t *  attr,
int  inheritsched 
)

Set inheritsched attribute.

This service set to inheritsched the value of the inheritsched attribute in the attribute object attr.

Threads created with this attribute set to PTHREAD_INHERIT_SCHED will use the same scheduling policy and priority as the thread calling pthread_create(). Threads created with this attribute set to PTHREAD_EXPLICIT_SCHED will use the value of the schedpolicy attribute as scheduling policy, and the value of the schedparam attribute as scheduling priority.

Parameters
attrattribute object;
inheritschedvalue of the inheritsched attribute, PTHREAD_INHERIT_SCHED or PTHREAD_EXPLICIT_SCHED.
Returns
0 on success;
an error number if:
  • EINVAL, attr or inheritsched is invalid.
See Also
Specification.

Referenced by rt_task_create().

int pthread_attr_setname_np ( pthread_attr_t *  attr,
const char *  name 
)

Set name attribute.

This service set to name, the value of the name attribute in the attribute object attr.

The name attribute is the name under which a thread created with the attribute object attr will appear under /proc/xenomai/sched.

If name is NULL, a unique default name will be used.

This service is a non-portable extension of the POSIX interface.

Parameters
attrattribute object;
namevalue of the name attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid;
  • ENOMEM, insufficient memory exists in the system heap to duplicate the name string, increase CONFIG_XENO_OPT_SYS_HEAPSZ.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • Xenomai kernel-space thread.
int pthread_attr_setschedparam ( pthread_attr_t *  attr,
const struct sched_param *  par 
)

Set schedparam attribute.

This service set to par, the limited form of the schedparam attribute in the attribute object attr.

The limited form only defines the sched_priority member, that is sufficent to hold the scheduling parameter for SCHED_FIFO, SCHED_RR and SCHED_OTHER class members. Threads created with attr will use the value of this attribute as a scheduling priority if the attribute inheritsched is set to PTHREAD_EXPLICIT_SCHED. Valid priorities range from 1 to 99.

Parameters
attrattribute object;
parvalue of the schedparam attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr or par is invalid.
See Also
Specification.

Referenced by rt_task_create().

int pthread_attr_setschedparam_ex ( pthread_attr_t *  attr,
const struct sched_param_ex *  par 
)

Set extended schedparam_ex attribute.

This service is an extended version of pthread_attr_setschedparam(), that also supports Xenomai-specific or additional POSIX scheduling policies, which are not available with the host Linux environment.

Typically, SCHED_SPORADIC or SCHED_TP parameters can be set using this call.

Parameters
attrattribute object;
parvalue of the schedparam attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr or par is invalid.
See Also
Specification.
int pthread_attr_setschedpolicy ( pthread_attr_t *  attr,
int  policy 
)

Set schedpolicy attribute.

This service set to policy the value of the policy attribute in the attribute object attr.

Threads created with the attribute object attr use the value of this attribute as scheduling policy if the inheritsched attribute is set to PTHREAD_EXPLICIT_SCHED. The value of this attribute is one of SCHED_FIFO, SCHED_RR, SCHED_SPORADIC, SCHED_TP or SCHED_OTHER.

Parameters
attrattribute object;
policyvalue of the policy attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr or policy is invalid.
See Also
Specification.

Referenced by rt_task_create().

int pthread_attr_setscope ( pthread_attr_t *  attr,
int  scope 
)

Set contention scope attribute.

This service set to scope the value of the scope attribute in the attribute object attr.

The scope attribute represents the scheduling contention scope of threads created with the attribute object attr. This implementation only supports the value PTHREAD_SCOPE_SYSTEM.

Parameters
attrattribute object;
scopevalue of the scope attribute.
Returns
0 on success;
an error number if:
  • ENOTSUP, scope is an unsupported value of the scope attribute.
  • EINVAL, attr is invalid.
See Also
Specification.
int pthread_attr_setstacksize ( pthread_attr_t *  attr,
size_t  stacksize 
)

Set stacksize attribute.

This service set to stacksize, the value of the stacksize attribute in the attribute object attr.

The stacksize attribute is used as the stack size of the threads created using the attribute object attr.

The minimum value for this attribute is PTHREAD_STACK_MIN.

Parameters
attrattribute object;
stacksizevalue of the stacksize attribute.
Returns
0 on success;
an error number if:
  • EINVAL, attr or stacksize is invalid.
See Also
Specification.

Referenced by rt_task_create().