ThreadCtl(), ThreadCtl_r()

Control a thread

Synopsis:

#include <sys/neutrino.h>

int ThreadCtl( int cmd, 
               void * data );

int ThreadCtl_r( int cmd, 
                 void * data );

Description:

The ThreadCtl() and ThreadCtl_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls allow you to make QNX-specific changes to a thread. The following calls are defined:

ThreadCtl(_NTO_TCTL_IO, 0)

Let the thread execute the IO opcodes in, ins, out, outs, cli, sti on architectures where it has the appropriate privilege and let it attach IRQ handlers. You need root permissions to use this command. If a thread attempts to use these opcodes without successfully executing this call, the thread faults with a SIGSEGV when the opcode is attempted.

Threads created by the calling thread do inherit the _NTO_TCTL_IO status.

ThreadCtl(_NTO_TCTL_RUNMASK, (int)runmask)

Set processor affinity for the calling thread in a multi-processor system. Each set bit in runmask represents a processor that the thread can run on.

By default, a thread's runmask is set to all ones, which allows it to run on any available processor. A value of 0x01 would, for example, force the thread to only run on the first processor.

Systems designers can use _NTO_TCTL_RUNMASK to optimize the runtime performance of their system by, for example, relegating nonrealtime threads to a specific processor. In general, this shouldn't be necessary, since the QNX realtime scheduler always preempts a lower-priority thread immediately when a higher priority thread becomes ready.

The main effect of processor locking is the effectiveness of the CPU cache, since threads can be prevented from migrating.

Threads created by the calling thread don't inherit the _NTO_TCTL_RUNMASK status.

ThreadCtl(_NTO_TCTL_THREADS_CONT, 0)

Unfreeze all threads in the current process that were frozen using the _NTO_TCTL_THREADS_HOLD command.

ThreadCtl(_NTO_TCTL_THREADS_HOLD, 0)

Freeze all threads in the current process except the calling thread.

Threads created by the calling thread aren't frozen.

The data pointer is reserved for passing extra data for new commands that may be introduced in the future.

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ThreadCtl(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
ThreadCtl_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EPERM: The process doesn't have superuser capabilities.

Classification:

QNX 6

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes