Thread creation attributes.
[Threads management services.]

Collaboration diagram for Thread creation attributes.:

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).


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_setschedparam (pthread_attr_t *attr, const struct sched_param *par)
 Set schedparam 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.


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:
attr attribute object;
mask address 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:
attr attribute object
detachstate address 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:
attr attribute object;
fp address 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:
attr attribute object;
inheritsched address 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:
attr attribute object;
name address 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 value of the schedparam attribute in the attribute object attr.

The only member of the sched_param structure used by this implementation is sched_priority. 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:
attr attribute object;
par address 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_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 or SCHED_OTHER.

Parameters:
attr attribute object;
policy address 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:
attr attribute object;
scope address 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:
attr attribute object;
stacksize address 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:
attr address of the thread attributes object to initialize.
Returns:
0.
See also:
Specification.
Examples:
rtcan_rtt.c.

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:
attr attribute object;
mask address 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:
attr attribute object;
detachstate value of the detachstate attribute.
Returns:
0 on success;

an error number if:

  • EINVAL, the attribute object attr is invalid
See also:
Specification.
Examples:
rtcan_rtt.c.

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:
attr attribute object;
fp value 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:
attr attribute object;
inheritsched value 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.

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:
attr attribute object;
name value 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 value of the schedparam attribute in the attribute object attr.

The only member of the sched_param structure used by this implementation is sched_priority. 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:
attr attribute object;
par value 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 or SCHED_OTHER.

Parameters:
attr attribute object;
policy value of the policy attribute.
Returns:
0 on success;

an error number if:

  • EINVAL, attr or policy is invalid.
See also:
Specification.

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:
attr attribute object;
scope value 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:
attr attribute object;
stacksize value of the stacksize attribute.
Returns:
0 on success;

an error number if:

  • EINVAL, attr or stacksize is invalid.
See also:
Specification.
Examples:
rtcan_rtt.c.


Generated on Mon Mar 24 18:02:44 2008 for Xenomai API by  doxygen 1.5.3