thread.cpp File Reference

Implementation of the Thread Runner and Managers. More...

#include "cppthread/thread.h"
#include "cppthread/exception.h"
#include "cppthread/guard.h"
#include "cppthread/log.h"
#include "cppthread/runner.h"
#include <snapdev/glob_to_list.h>
#include <fstream>
#include <signal.h>
#include <sys/auxv.h>
#include <sys/stat.h>
#include <sys/syscall.h>
#include <sys/sysinfo.h>
#include <unistd.h>
#include <snapdev/poison.h>

Include dependency graph for thread.cpp:

Go to the source code of this file.

Functions
void *	cppthread::func_internal_start (void *system_thread)
	Start the actual thread.
std::string	cppthread::get_boot_id ()
	Retrieve the boot UUID.
std::string	cppthread::get_current_thread_name ()
	Retrieve the name of the current thread.
int	cppthread::get_number_of_available_processors ()
	Retrieve the number of processors currently usable.
pid_t	cppthread::get_pid_max ()
	Get the maximum process identifier.
std::size_t	cppthread::get_thread_count ()
	Get the number of threads still not joined in this process.
process_ids_t	cppthread::get_thread_ids (pid_t pid)
	Retrieve the list of threads for a given process.
std::string	cppthread::get_thread_name (pid_t tid)
	Retrieve the name of a thread.
int	cppthread::get_total_number_of_processors ()
	Retrieve the number of processors available on this system.
pid_t	cppthread::gettid ()
	Get the thread identifier of the current thread.
bool	cppthread::is_process_running (pid_t pid)
	Check whether a process is running or not.
bool	cppthread::is_using_vdso ()
	Certain functions may be implemented using the vDSO library.
int	cppthread::set_current_thread_name (std::string const &name)
	Set the name of the currently running thread.
int	cppthread::set_thread_name (pid_t tid, std::string const &name)
	Set the name of the specified thread.

Detailed Description

This file includes the implementation used by the cppthread environment.

Definition in file thread.cpp.

Function Documentation

func_internal_start()

void * cppthread::func_internal_start

(

void *

system_thread

)

This function is called when starting the thread. This is a static function since pthread can only accept such a function pointer.

The function then calls the internal_thread().

Note

The function parameter is a void * instead of thread because that way the function signature matches the signature the pthread_create() function expects.

Parameters

[in]

system_thread

The thread pointer.

Returns

We return a null pointer, which we do not use because we expect users to pass results in a different way (i.e. using the fifo).

Definition at line 293 of file thread.cpp.

get_boot_id()

std::string cppthread::get_boot_id

(

)

The Linux kernel generates a UUID on a reboot. This allows software to determine whether the computer was rebooted since the last time it was used.

On computers where there is no boot identifier, this function returns an empty string.

Returns

The boot UUID as a string or an empty string if not available.

Definition at line 1372 of file thread.cpp.

References cppthread::get_boot_id().

Referenced by cppthread::get_boot_id().

Here is the call graph for this function:

Here is the caller graph for this function:

get_current_thread_name()

std::string cppthread::get_current_thread_name

(

)

This function reads the name of the currently running thread by reading its /proc/\<tid>/comm file. See the get_thread_name() for more details.

Returns

The name of the current thread.

See also

get_thread_name()

gettid()

Definition at line 1236 of file thread.cpp.

References cppthread::get_current_thread_name(), cppthread::get_thread_name(), and cppthread::gettid().

Referenced by cppthread::get_current_thread_name().

Here is the call graph for this function:

Here is the caller graph for this function:

get_number_of_available_processors()

int cppthread::get_number_of_available_processors

(

)

This function returns the number of processors that are currently running on this system. This is usually what you want to know about to determine how many threads to run in parallel.

This function is going to be equal or less than what the get_total_number_of_processors() returns. For example, on some systems a processors can be made offline. This is useful to save energy when the total load decreases under a given threshold.

Note

What is the right number of threads needed in a thread pool? If you have worker threads that do a fairly small amount of work, then having a number of threads equal to two times the number of available thread is still sensible:

pool_size = get_number_of_available_processors() * 2;

This is particularly true when threads perform I/O with high latency (i.e. read/write from a hard drive or a socket.)

If your thread does really intensive work for a while (i.e. one thread working on one 4Mb image,) then the pool size should be limited to one worker per CPU:

pool_size = get_number_of_available_processors();

Also, if you know that you will never get more than n objects at a time in your input, then the maximum number of threads needed is going to be n. In most cases n is going to be larger than the number of processors although now that we can have machines with over 100 CPUs, make sure to clamp your pool_size parameter to n if known ahead of time.

Returns

The number of processors currently available for your threads.

See also

get_total_number_of_processors()

Definition at line 1031 of file thread.cpp.

References cppthread::get_number_of_available_processors().

Referenced by cppthread::get_number_of_available_processors().

Here is the call graph for this function:

Here is the caller graph for this function:

get_pid_max()

pid_t cppthread::get_pid_max

(

)

This function retrieves the maximum that getpid() may return.

The value is cached by the function (in a static variable.) Note that is somewhat wrong since that number can be changed dynamically, although I've seen too many people ever doing so. If your process depends on it, then stop your process, make the change, and restart your process.

Note that this function returns the maximum that getpid() can return and not the maximum + 1. In other words, the value returned by this function is inclusive (i.e. in most cases you will get 32767 which a process can have as its PID.)

So far, the documentation I've found about the value in the kernel file is not clear about whether that value is inclusive or the last possible PID + 1. I wrote a small test to get the answer and each time the maximum PID I could get was 32767 when the content of "/proc/sys/kernel/pid_max" returns 32768. This is how most C software functions so I am pretty sure our function here is correct.

Note

The following code often breaks with a fork() failed error. Once you reach the rollover point, though, it cleanly stops on its own. It will print the PID just before the rollover and just after. For example, I get:

pid = 32765
pid = 32766
pid = 32767
pid = 301

Of course, if you start this process with the smallest possible PID (such as 301) it will not stop on its own unless the fork() fails which is very likely anyway.

int main ()
{
    pid_t pid;
 
    pid_t start = getpid();
    for(int i(0);; ++i)
    {
        pid = fork();
        if(pid == 0)
        {
            exit(0);
        }
        if(pid == -1)
        {
            std::cerr << "fork() failed...\n";
            exit(1);
        }
        std::cerr << "pid = " << pid << "\n";
        if(pid < start)
        {
            break;
        }
        pthread_yield();
    }
 
    return 0;
}

Note

We use this function in snaplock which is affected in case the parameter get dynamically changed by writing to "/proc/sys/kernel/pid_max".

Returns

The maximum getpid() can return or -1 if it can't be determined.

Definition at line 1129 of file thread.cpp.

References cppthread::get_pid_max().

Referenced by cppthread::get_pid_max().

Here is the call graph for this function:

Here is the caller graph for this function:

get_thread_count()

std::size_t cppthread::get_thread_count

(

)

This function gets the number of currently running threads present in this process. The function is expected to return at least 1 since it includes the currently running thread (i.e. main thread).

It can be called from a thread and is dynamic so the returned number can change on each call.

Note

If the /proc file system is somehow not accessible, then the function may return -1.

Returns

The number of threads or -1 on an error.

Definition at line 1399 of file thread.cpp.

References cppthread::get_thread_count().

Referenced by cppthread::get_thread_count().

Here is the call graph for this function:

Here is the caller graph for this function:

get_thread_ids()

process_ids_t cppthread::get_thread_ids

(

pid_t

pid

)

This function reads the list of PID from /proc/<pid>/task/\* which is the list of threads of a process has. If only one PID, then this is the main process PID and the process has no threads currently running.

Parameters

[in]

pid

The parent process to be searched for threads.

Returns

A vector of PIDs.

Definition at line 1278 of file thread.cpp.

References cppthread::get_thread_ids().

Referenced by cppthread::get_thread_ids().

Here is the call graph for this function:

Here is the caller graph for this function:

get_thread_name()

std::string cppthread::get_thread_name

(

pid_t

tid

)

This function reads the name of the tid thread by reading its /proc/\<tid>/comm file.

This function is different from the pthread_getname_np() which will return the in memory name. If you have access to your runner, you may instead want to use its get_name() function. Note that the name of a runner cannot be changed so it may be considered more authoritative.

Parameters

[in]

tid

The thread identifier (its number, not pthread_t).

Returns

The name of the specified thread.

See also

get_current_thread_name()

gettid()

Definition at line 1259 of file thread.cpp.

References cppthread::get_thread_name().

Referenced by cppthread::get_current_thread_name(), and cppthread::get_thread_name().

Here is the call graph for this function:

Here is the caller graph for this function:

get_total_number_of_processors()

int cppthread::get_total_number_of_processors

(

)

This function returns the number of processors available on this system.

Attention

Note that the OS may not be using all of the available processors. This function returns the total number, including processors that are not currently usable by your application. Most often, you probably want to call get_number_of_available_processors() instead.

Returns

The total number of processors on this system.

See also

get_number_of_available_processors()

Definition at line 979 of file thread.cpp.

References cppthread::get_total_number_of_processors().

Referenced by cppthread::get_total_number_of_processors().

Here is the call graph for this function:

Here is the caller graph for this function:

gettid()

pid_t cppthread::gettid

(

)

This function retrieves the thread identifier of the current thread. In most cases, this is only useful to print out messages to a log including the thread identifier. This identifier is equivalent to the pid_t returned by getpid() but specific to the running thread.

Returns

The thread identifier.

Definition at line 1047 of file thread.cpp.

References cppthread::gettid().

Referenced by cppthread::get_current_thread_name(), cppthread::gettid(), cppthread::thread::internal_thread(), cppthread::set_current_thread_name(), and cppthread::thread::start().

Here is the call graph for this function:

Here is the caller graph for this function:

is_process_running()

bool cppthread::is_process_running

(

pid_t

pid

)

This function checks whether the /proc/<pid> directory exists. If so, that means that the process with pid is current running.

Note

Keep in mind that between the time this function checks whether a process is running or not and the time it returns, the given process may have stopped or a new process may have been started.

Also, security wise, this is not safe except around the time a process quits and even though, on a very heavy system starting new processes all the time, it may re-use the same pid very quickly.

Parameters

[in]

pid

The process identifier to check.

Returns

true if the process is currently running.

Definition at line 1344 of file thread.cpp.

References cppthread::is_process_running().

Referenced by cppthread::is_process_running().

Here is the call graph for this function:

Here is the caller graph for this function:

is_using_vdso()

bool cppthread::is_using_vdso

(

)

The vDSO library is a Linux extension using a small library which gets loaded at the time a new process gets loaded. This library is common to all processes and allows for some functions such as gettimeofday(2) to be implemented without having to do a kernel system call. This improves speed dramatically.

The side effect is that it can affect the functionality of some calls such as time(2), because the time function can end up being off by up to 1 second.

If this function returns true, then know that your implementation of the time(2) function may not work exactly as expected. In that case, it is important that you consider using clock_gettime(2) instead. That latter function will properly adjust the second if it would otherwise be off.

Returns

true if the vDSO is in use.

Definition at line 1431 of file thread.cpp.

References cppthread::is_using_vdso().

Referenced by cppthread::is_using_vdso().

Here is the call graph for this function:

Here is the caller graph for this function:

set_current_thread_name()

int cppthread::set_current_thread_name

(

std::string const &

name

)

This function is used to set the name of the currently running thread.

Parameters

[in]

name

The name of the thread.

Returns

0 if the function worked, -1 on error.

Definition at line 1161 of file thread.cpp.

References cppthread::gettid(), cppthread::set_current_thread_name(), and cppthread::set_thread_name().

Referenced by cppthread::thread::internal_thread(), and cppthread::set_current_thread_name().

Here is the call graph for this function:

Here is the caller graph for this function:

set_thread_name()

int cppthread::set_thread_name	(	pid_t	tid,
		std::string const &	name
	)

This function changes the name of one of your threads. In most cases, you should let the runner set the name of the thread on construction.

This function should be used only if the name somehow changes over time, for example:

The thread is a worker thread and you want the name to reflect what the worker is currently doing. However, do that only if the worker is going to do work for a while, otherwise it's likely going to be rather useless (i.e. htop refresh rate is 1 to 2 seconds).

Exceptions

cppthread_invalid_error	This exception is raised if the name is empty.
cppthread_out_of_range	This exception is raised if the name is too long. Linux limits the name of a thread to 15 characters (the buffer has a limit of 16 characters).

Parameters

[in]	tid	The thread identifier (its number, not pthread_t).
[in]	name	The name of the thread.

Returns

0 if the function worked, -1 on error.

Definition at line 1194 of file thread.cpp.

References cppthread::set_thread_name().

Referenced by cppthread::set_current_thread_name(), and cppthread::set_thread_name().

Here is the call graph for this function:

Here is the caller graph for this function: