pthread_getunique_np()--Retrieve Unique ID for Target Thread

 #include <pthread.h>
 int pthread_getunique_np(pthread_t *thread, pthread_id_np_t *id);  

The pthread_getunique_np() function retrieves the unique integral identifier that can be used to identify the thread in some context for application debugging or tracing support.

In some implementations, the thread ID is equivalent to the pthread_t type. In the i5/OS implementation, the pthread_t is an opaque Pthread handle. For the ability to identify a thread using a thread ID (unique number), the pthread_getunique_np() and pthread_getthreadid_np() interfaces are provided.

The i5/OS machine implementation of threads provides a 64-bit thread ID. The thread ID is returned as a structure containing the high and low order 4 bytes of the 64-bit ID. This allows applications created by compilers that do not yet support 64-bit integral values to effectively use the 64-bit thread ID.

If your code requires the unique integer identifier for the calling thread often, or in a loop, the pthread_getthreadid_np() function can significantly improve performance over the combination of pthread_self() and pthread_getunique_np() calls that provide equivalent behavior.

For example:

pthread_id_np_t   tid;
tid = pthread_getthreadid_np();

is significantly faster than these calls, but provides the same behavior.

pthread_id_np_t   tid;
pthread_t         self;
self = pthread_self();
pthread_getunique_np(&self, &tid);

As always, if you are calling any function too often, you can improve performance by storing the results in a variable or passing to other functions that require the results.

Note:This function is not portable.

Authorities and Locks

None.

Parameters

thread

(Input) Address of the thread to retrieve the unique integer ID for

id

(Output) Address of the thread ID structure to contain the 64-bit thread ID.

Return Value

0

pthread_getunique_np() was successful.

value

pthread_getunique_np() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_getunique_np() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions
  
  
• pthread_self()--Get Pthread Handle
  
  
• pthread_getthreadid_np()--Retrieve Unique ID for Calling Thread
  
  

Example

See Code disclaimer information for information pertaining to code examples.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

#define         NUMTHREADS     3

void *threadfunc(void *parm)
{
  pthread_id_np_t tid;
  pthread_t     me = pthread_self();

  pthread_getunique_np(&me, &tid);
  printf("Thread 0x%.8x %.8x started\n", tid);
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread[NUMTHREADS];
  int                   rc=0;
  pthread_id_np_t       tid;
  int                   i=0;
  pthread_t             me = pthread_self();

  printf("Enter Testcase - %s\n", argv[0]);

  pthread_getunique_np(&me, &tid);
  printf("Main Thread 0x%.8x %.8x\n", tid);
 
  printf("Create %d threads using joinable attributes\n",
         NUMTHREADS);
  for (i=0; i<NUMTHREADS; ++i) {
    rc = pthread_create(&thread[i], NULL, threadfunc, NULL);
    checkResults("pthread_create()\n", rc);
    pthread_getunique_np(&thread[i], &tid);
    printf("Created thread 0x%.8x %.8x\n", tid);
  }

  printf("Join to threads\n");
  for (i=0; i<NUMTHREADS; ++i) {
    rc = pthread_join(thread[i], NULL);
    checkResults("pthread_join()\n", rc);
  }

  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPGETU0
Main Thread 0x00000000 0000006c
Create 3 threads using joinable attributes
Created thread 0x00000000 0000006d
Thread 0x00000000 0000006d started
Created thread 0x00000000 0000006e
Created thread 0x00000000 0000006f
Join to threads
Thread 0x00000000 0000006f started
Thread 0x00000000 0000006e started
Main completed