Thread Runner and Managers. More...

#include <cppthread/mutex.h>
#include <libexcept/scoped_signal_mask.h>
#include <functional>
#include <string>
#include <vector>

Include dependency graph for thread.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	cppthread::thread
	A thread object that ensures proper usage of system threads. More...

Typedefs
typedef std::vector< pid_t >	cppthread::process_ids_t
	A list of identifiers representing various processes.

Functions
int	cppthread::deswappify (pid_t pid)
	Go through the swapped out sections of a process and deswappify them.

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.

Variables
constexpr pid_t	cppthread::PID_UNDEFINED = static_cast<pid_t>(-1)
	The value a PID variable is set to when not representing a process.

constexpr pthread_t	cppthread::THREAD_UNDEFINED = static_cast<pthread_t>(-1)
	An invalid thread identifier for initialization.

Detailed Description

This file includes the declaration and implementation (For templates) of classes used to manage threads the easy way. Especially, our implementation is aware of object destructors so a thread manager (snap_thread) can be destroyed. It will automatically and properly wait for its runner (the actual system pthread) to exit before finishing up its and its runner clean up.

Definition in file thread.h.

Typedef Documentation

◆ process_ids_t

cppthread::process_ids_t

This type defines a vector that can hold identifiers to various processes.

Definition at line 125 of file thread.h.

Function Documentation

◆ deswappify()

int cppthread::deswappify ( pid_t pid )

This function reads the memory map of a process and searches for sections of memory that were swapped out and read them back in memory.

Todo:: Implement necessary check to make sure the data can be swapped back in without causing immediate issues.

Todo:: Actually write a function that reads all the blocks and save them in a list with a grand total for the size. Then we can make the decision of swapping that process back in or not.

Parameters

[in] pid The process identifier.

Returns: 0 if no error occurred, an errno otherwise

Definition at line 83 of file deswappify.cpp.

References cppthread::deswappify(), and cppthread::end().

Referenced by cppthread::deswappify().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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:

Variable Documentation

◆ PID_UNDEFINED

cppthread::PID_UNDEFINED = static_cast<pid_t>(-1)

constexpr

In many cases we want to be able to initialize a pid_t variable with some default value. This variable is generally the best choice.

pid_t f_my_process = PID_UNDEFINED;

Definition at line 59 of file thread.h.

Referenced by cppthread::thread::internal_thread().

◆ THREAD_UNDEFINED

cppthread::THREAD_UNDEFINED = static_cast<pthread_t>(-1)

constexpr

In many cases we want to be able to initialize a pthread_t variable with some default value. This variable is generally the best choice.

pthread_t f_my_thread = THREAD_UNDEFINED;

Definition at line 60 of file thread.h.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ process_ids_t

Function Documentation

◆ deswappify()

◆ get_boot_id()

◆ get_current_thread_name()

◆ get_number_of_available_processors()

◆ get_pid_max()

◆ get_thread_count()

◆ get_thread_ids()

◆ get_thread_name()

◆ get_total_number_of_processors()

◆ gettid()

◆ is_process_running()

◆ is_using_vdso()

◆ set_current_thread_name()

◆ set_thread_name()

Variable Documentation

◆ PID_UNDEFINED

◆ THREAD_UNDEFINED