thread_manager¶

Bindings for basic::thread_manager namespace

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadAllocation¶

Bases: pybind11_object

property thread_ids¶

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo¶

Bases: pybind11_object

assign(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo, : pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo) → pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo¶: C++: basic::thread_manager::RosettaThreadAssignmentInfo::operator=(const class basic::thread_manager::RosettaThreadAssignmentInfo &) –> class basic::thread_manager::RosettaThreadAssignmentInfo &

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager¶

Bases: SingletonBase_basic_thread_manager_RosettaThreadManager_t

A manager that maintains a threadpool and handles requests for threads for multithreaded execution of functions. This allows multithreading at many different levels in the Rosetta library hierarchy, from job-level parallel execution down to parallel computation of a score, gradient vector, or interaction graph.

In single-threaded builds, this object still exists. It accepts vectors of work and executes them directly, in this case.

static get_instance() → basic::thread_manager::RosettaThreadManager¶: C++: utility::SingletonBase<basic::thread_manager::RosettaThreadManager>::get_instance() –> class basic::thread_manager::RosettaThreadManager *

get_rosetta_thread_index(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager) → int¶

Get the Rosetta thread index.

C++: basic::thread_manager::RosettaThreadManager::get_rosetta_thread_index() const –> unsigned long

release_threads(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager, allocation: pyrosetta.rosetta.basic.thread_manager.RosettaThreadAllocation) → None¶

deallocate threads given by reserve_threads()

This is called by RosettaThreadAllocation’s destructor, so you don’t need to worry about it

C++: basic::thread_manager::RosettaThreadManager::release_threads(struct basic::thread_manager::RosettaThreadAllocation &) –> void

reserve_threads(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager, requested_thread_count: int, thread_assignment: pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo) → pyrosetta.rosetta.basic.thread_manager.RosettaThreadAllocation¶

Allocate threads before supplying the work vector

C++: basic::thread_manager::RosettaThreadManager::reserve_threads(const unsigned long, class basic::thread_manager::RosettaThreadAssignmentInfo &) –> struct basic::thread_manager::RosettaThreadAllocation

run_function_in_threads(*args, **kwargs)¶

Overloaded function.

run_function_in_threads(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager, function_to_execute: std::function<void ()>, requested_thread_count: int, key: basic::thread_manager::RosettaThreadManagerAdvancedAPIKey, thread_assignment: pyrosetta.rosetta.basic.thread_manager.RosettaThreadAssignmentInfo) -> None

ADVANCED API THAT SHOULD NOT BE USED IN MOST CIRCUMSTANCES. Given a function that was bundled with its

arguments with std::bind, run it in many threads. This calls RosettaThreadPool::run_function_in_threads for the already-running thread pool. If the thread pool has not been created, it first creates it by calling create_thread_pool(). IF YOU DECIDE TO USE THE ADVANCED API, YOU MUST: 1. Pass this function a RosettaThreadManagerAdvancedAPIKey from the calling context. Since the RosettaThreadManagerAdvancedAPIKey class has a private constructor, it can only be created in whitelisted contexts in its friend list, which means that you must: 2. Add the class that calls this advanced API to the friend list for the RosettaThreadManagerAdvancedAPIKey class. Since this will trigger breakage of the central_class_modification regression test, you must finally: 3. Justify to the developer community why you must call this interface and not the safer, basic interface (do_work_vector_in_threads) in both the comments in RosettaThreadManagerAdvancedAPIKey’s friend list, the comments in the calling class, AND in your pull request description. Andrew Leaver-Fay and Vikram K. Mulligan will both scrutinize this closely. It is highly recommended that before using the run_function_in_threads() function, you first contact Andrew or Vikram and discuss whether it is possible to do what you want to do using the basic API (the do_work_vector_in_threads() function).

The function is assigned to as many threads as the RosettaThreadPool decides to assign it to, always including the thread from which the request originates. It is guaranteed to run in 1 <= actual_thread_count <= requested_thread_count threads. After assigning the function to up to (requsted_thread_count - 1) other threads, the function executes in the current thread, then the current thread blocks until the assigned threads report that they are idle. All of this is handled by the RosettaThreadPool class (or its derived classes, which may have) different logic for assigning thread requests to threads).

A RosettaThreadAssignmentInfo object should be passed in. It will be populated with the number of threads requested, the number actually assigned, the indices of the assigned threads, and a map of system thread ID to Rosetta thread index. The same owning pointer may optionally be provided to the function to execute by the calling function if the function to execute requires access to this information. Note also that the function passed in is responsible for ensuring that it is able to carry out a large block of work, alone or concurrently with many copies of itself in parallel threads, in a threadsafe manner. Finally, note that this function requires a RosettaThreadManagerAdvancedAPIKey, which can only be instantiated by friend classes in the whitelist in the RosettaThreadManagerAdvancedAPIKey class definition. This ensures that only select classes can access the advanced RosettaThreadManager API.

C++: basic::thread_manager::RosettaThreadManager::run_function_in_threads(class std::function<void (void)> &, const unsigned long, const class basic::thread_manager::RosettaThreadManagerAdvancedAPIKey &, class basic::thread_manager::RosettaThreadAssignmentInfo &) –> void

run_function_in_threads(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManager, function_to_execute: std::function<void ()>, key: basic::thread_manager::RosettaThreadManagerAdvancedAPIKey, allocation: pyrosetta.rosetta.basic.thread_manager.RosettaThreadAllocation) -> None

ADVANCED API THAT SHOULD NOT BE USED IN MOST CIRCUMSTANCES. Given a function that was bundled with its

arguments with std::bind, run it in many threads. This calls RosettaThreadPool::run_function_in_threads for the already-running thread pool. If the thread pool has not been created, it first creates it by calling create_thread_pool(). IF YOU DECIDE TO USE THE ADVANCED API, YOU MUST: 1. Pass this function a RosettaThreadManagerAdvancedAPIKey from the calling context. Since the RosettaThreadManagerAdvancedAPIKey class has a private constructor, it can only be created in whitelisted contexts in its friend list, which means that you must: 2. Add the class that calls this advanced API to the friend list for the RosettaThreadManagerAdvancedAPIKey class. Since this will trigger breakage of the central_class_modification regression test, you must finally: 3. Justify to the developer community why you must call this interface and not the safer, basic interface (do_work_vector_in_threads) in both the comments in RosettaThreadManagerAdvancedAPIKey’s friend list, the comments in the calling class, AND in your pull request description. Andrew Leaver-Fay and Vikram K. Mulligan will both scrutinize this closely. It is highly recommended that before using the run_function_in_threads() function, you first contact Andrew or Vikram and discuss whether it is possible to do what you want to do using the basic API (the do_work_vector_in_threads() function).

The function is assigned to as many threads as the RosettaThreadPool decides to assign it to, always including the thread from which the request originates. It is guaranteed to run in 1 <= actual_thread_count <= requested_thread_count threads. After assigning the function to up to (requsted_thread_count - 1) other threads, the function executes in the current thread, then the current thread blocks until the assigned threads report that they are idle. All of this is handled by the RosettaThreadPool class (or its derived classes, which may have) different logic for assigning thread requests to threads).

A RosettaThreadAssignmentInfo object should be passed in. It will be populated with the number of threads requested, the number actually assigned, the indices of the assigned threads, and a map of system thread ID to Rosetta thread index. The same owning pointer may optionally be provided to the function to execute by the calling function if the function to execute requires access to this information. Note also that the function passed in is responsible for ensuring that it is able to carry out a large block of work, alone or concurrently with many copies of itself in parallel threads, in a threadsafe manner. Finally, note that this function requires a RosettaThreadManagerAdvancedAPIKey, which can only be instantiated by friend classes in the whitelist in the RosettaThreadManagerAdvancedAPIKey class definition. This ensures that only select classes can access the advanced RosettaThreadManager API.

C++: basic::thread_manager::RosettaThreadManager::run_function_in_threads(class std::function<void (void)> &, const class basic::thread_manager::RosettaThreadManagerAdvancedAPIKey &, struct basic::thread_manager::RosettaThreadAllocation &) –> void

static total_threads() → int¶

Get the total number of threads that have been launched or will be launched.

This corresponds to the -multithreading:total_threads option, but it does not access the options system repatedly.d

Always returns 1 in the non-threaded build.

C++: basic::thread_manager::RosettaThreadManager::total_threads() –> unsigned long

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerAdvancedAPIKey¶

Bases: pybind11_object

A class containing no private member data and only a constructor as a private member function, with friendship to only those classes that should be able to access the advanced RosettaThreadManager API. Since the advanced API requires an instance of a RosettaThreadManagerAdvancedAPIKey, this ensures that only those classes can access the advanced API.

Vikram K. Mulligan (vmulligan.org)

If you use the RosettaThreadManager::run_function_in_threads() advanced API, you must modify this class to add your calling context to the friend list for this class. If you do not do this, you will not be able to create an instance of this class to pass to that function. Whitelisting your calling context will light up the central_class_modification integration test, and this means that you will be forced to justify why you need the advanced API before you can merge your code. It is STRONGLY recommended that you try to use the basic API (the RosettaThreadManager::do_work_vector_in_threads() function), which is much safer, if you possibly can. If you want to discuss the best way to multi-thread your code, please talk to Andrew Leaver-Fay or Vikram K. Mulligan BEFORE starting.

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker¶

Bases: SingletonBase_basic_thread_manager_RosettaThreadManagerInitializationTracker_t

A singleton that tracks whether we have already launched threads or not.

static get_instance() → basic::thread_manager::RosettaThreadManagerInitializationTracker¶: C++: utility::SingletonBase<basic::thread_manager::RosettaThreadManagerInitializationTracker>::get_instance() –> class basic::thread_manager::RosettaThreadManagerInitializationTracker *

mark_thread_manager_as_initialized(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker) → None¶

Store the fact that threads have been launched.

C++: basic::thread_manager::RosettaThreadManagerInitializationTracker::mark_thread_manager_as_initialized() –> void

mark_thread_manager_initialization_as_begun(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker) → None¶

Store the fact that thread lauch has started.

C++: basic::thread_manager::RosettaThreadManagerInitializationTracker::mark_thread_manager_initialization_as_begun() –> void

thread_manager_initialization_begun(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker) → bool¶

Determine whether thread launch has started.

C++: basic::thread_manager::RosettaThreadManagerInitializationTracker::thread_manager_initialization_begun() const –> bool

thread_manager_was_initialized(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker) → bool¶

Determine whether threads have been launched.

C++: basic::thread_manager::RosettaThreadManagerInitializationTracker::thread_manager_was_initialized() const –> bool

total_threads(self: pyrosetta.rosetta.basic.thread_manager.RosettaThreadManagerInitializationTracker) → int¶

Get the total number of threads that have been launched or which

will be launched.

Read from options system. If options system specifies “0”, set to number of cores in system.

C++: basic::thread_manager::RosettaThreadManagerInitializationTracker::total_threads() const –> unsigned long

class pyrosetta.rosetta.basic.thread_manager.RosettaThreadRequestOriginatingLevel¶

Bases: pybind11_object

Members:

UNKNOWN

CORE_GENERIC

CORE_PACK

CORE_SCORING

PROTOCOLS_GENERIC

PROTOCOLS_MINIMIZATION_PACKING

PROTOCOLS_JOB_DISTRIBUTOR

APPLICATIONS_OR_APPLICATION_PROTOCOLS

INVALID

END_OF_LIST

APPLICATIONS_OR_APPLICATION_PROTOCOLS = <RosettaThreadRequestOriginatingLevel.APPLICATIONS_OR_APPLICATION_PROTOCOLS: 8>¶

CORE_GENERIC = <RosettaThreadRequestOriginatingLevel.CORE_GENERIC: 2>¶

CORE_PACK = <RosettaThreadRequestOriginatingLevel.CORE_PACK: 3>¶

CORE_SCORING = <RosettaThreadRequestOriginatingLevel.CORE_SCORING: 4>¶

END_OF_LIST = <RosettaThreadRequestOriginatingLevel.INVALID: 9>¶

INVALID = <RosettaThreadRequestOriginatingLevel.INVALID: 9>¶

PROTOCOLS_GENERIC = <RosettaThreadRequestOriginatingLevel.PROTOCOLS_GENERIC: 5>¶

PROTOCOLS_JOB_DISTRIBUTOR = <RosettaThreadRequestOriginatingLevel.PROTOCOLS_JOB_DISTRIBUTOR: 7>¶

PROTOCOLS_MINIMIZATION_PACKING = <RosettaThreadRequestOriginatingLevel.PROTOCOLS_MINIMIZATION_PACKING: 6>¶

UNKNOWN = <RosettaThreadRequestOriginatingLevel.UNKNOWN: 1>¶

property name¶

property value¶