Internal Thread Handling

Internal Thread Handling#

Rocprofiler SDK Developer API: Internal Thread Handling

Rocprofiler SDK Developer API 0.4.0

ROCm Profiling API and tools

Callbacks before and after threads created internally by libraries. More...

Data Structures
struct	rocprofiler_callback_thread_t
	opaque handle to an internal thread identifier which delivers callbacks for buffers More...

Typedefs
typedef void(*	rocprofiler_internal_thread_library_cb_t) (rocprofiler_runtime_library_t, void *)
	Callback type before and after internal thread creation.

Functions
rocprofiler_status_t	rocprofiler_at_internal_thread_create (rocprofiler_internal_thread_library_cb_t precreate, rocprofiler_internal_thread_library_cb_t postcreate, int libs, void *data)
	Invoke this function to receive callbacks before and after the creation of an internal thread by a library which as invoked on the thread which is creating the internal thread(s).

rocprofiler_status_t	rocprofiler_create_callback_thread (rocprofiler_callback_thread_t *cb_thread_id)
	Create a handle to a unique thread (created by rocprofiler) which, when associated with a particular buffer, will guarantee those buffered results always get delivered on the same thread. This is useful to prevent/control thread-safety issues and/or enable multithreaded processing of buffers with non-overlapping data.

rocprofiler_status_t	rocprofiler_assign_callback_thread (rocprofiler_buffer_id_t buffer_id, rocprofiler_callback_thread_t cb_thread_id)
	By default, all buffered results are delivered on the same thread. Using rocprofiler_create_callback_thread, one or more buffers can be assigned to deliever their results on a unique, dedicated thread.

Detailed Description

Callbacks before and after threads created internally by libraries.

Data Structure Documentation

◆ rocprofiler_callback_thread_t

struct rocprofiler_callback_thread_t

opaque handle to an internal thread identifier which delivers callbacks for buffers

See also: rocprofiler_create_callback_thread

Examples: api_buffered_tracing/client.cpp.

Definition at line 87 of file internal_threading.h.

Collaboration diagram for rocprofiler_callback_thread_t:

Data Fields
uint64_t	handle

Typedef Documentation

◆ rocprofiler_internal_thread_library_cb_t

typedef void(* rocprofiler_internal_thread_library_cb_t) (rocprofiler_runtime_library_t, void *)

Callback type before and after internal thread creation.

See also: rocprofiler_at_internal_thread_create

Definition at line 46 of file internal_threading.h.

Function Documentation

◆ rocprofiler_assign_callback_thread()

rocprofiler_status_t rocprofiler_assign_callback_thread	(	rocprofiler_buffer_id_t	buffer_id,
		rocprofiler_callback_thread_t	cb_thread_id
	)

By default, all buffered results are delivered on the same thread. Using rocprofiler_create_callback_thread, one or more buffers can be assigned to deliever their results on a unique, dedicated thread.

Parameters

[in]	buffer_id	Buffer identifier
[in]	cb_thread_id	Callback thread identifier via rocprofiler_create_callback_thread

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	Successful assignment of the delivery thread for the given buffer
ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED	Thread assignment is no longer available post-initialization
ROCPROFILER_STATUS_ERROR_THREAD_NOT_FOUND	Thread identifier did not match any of the threads created by rocprofiler
ROCPROFILER_STATUS_ERROR_BUFFER_NOT_FOUND	Buffer identifier did not match any of the buffers registered with rocprofiler

Examples: api_buffered_tracing/client.cpp.

◆ rocprofiler_at_internal_thread_create()

rocprofiler_status_t rocprofiler_at_internal_thread_create	(	rocprofiler_internal_thread_library_cb_t	precreate,
		rocprofiler_internal_thread_library_cb_t	postcreate,
		int	libs,
		void *	data
	)

Invoke this function to receive callbacks before and after the creation of an internal thread by a library which as invoked on the thread which is creating the internal thread(s).

Use the rocprofiler_runtime_library_t enumeration for specifying which libraries you want callbacks before and after the library creates an internal thread. These callbacks will be invoked on the thread that is about to create the new thread (not on the newly created thread). In thread-aware tools that wrap pthread_create, this can be used to disable the wrapper before the pthread_create invocation and re-enable the wrapper afterwards. In many cases, tools will want to ignore the thread(s) created by rocprofiler since these threads do not exist in the normal application execution, whereas the internal threads for HSA, HIP, etc. are created in normal application execution; however, the HIP, HSA, etc. internal threads are typically background threads which just monitor kernel completion and are unlikely to contribute to any performance issues. Please note that the postcreate callback is guaranteed to be invoked after the underlying system call to create a new thread but it does not guarantee that the new thread has been started. Please note, that once these callbacks are registered, they cannot be removed so the caller is responsible for ignoring these callbacks if they want to ignore them beyond a certain point in the application.

Parameters

[in]	precreate	Callback invoked immediately before a new internal thread is created
[in]	postcreate	Callback invoked immediately after a new internal thread is created
[in]	libs	Bitwise-or of libraries, e.g. `ROCPROFILER_LIBRARY \| ROCPROFILER_MARKER_LIBRARY` means the callbacks will be invoked whenever rocprofiler and/or the marker library create internal threads but not when the HSA or HIP libraries create internal threads.
[in]	data	Data shared between callbacks

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS There are currently no conditions which result in any other value, even if internal threads have already been created

Examples: api_buffered_tracing/client.cpp.

◆ rocprofiler_create_callback_thread()

rocprofiler_status_t rocprofiler_create_callback_thread ( rocprofiler_callback_thread_t * cb_thread_id )

Create a handle to a unique thread (created by rocprofiler) which, when associated with a particular buffer, will guarantee those buffered results always get delivered on the same thread. This is useful to prevent/control thread-safety issues and/or enable multithreaded processing of buffers with non-overlapping data.

Parameters

[in] cb_thread_id User-provided pointer to a rocprofiler_callback_thread_t

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_SUCCESS	Successful thread creation
ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED	Thread creation is no longer available post-initialization
ROCPROFILER_STATUS_ERROR	Failed to create thread

Examples: api_buffered_tracing/client.cpp.

Internal Thread Handling

Internal Thread Handling#

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ rocprofiler_callback_thread_t

Typedef Documentation

◆ rocprofiler_internal_thread_library_cb_t

Function Documentation

◆ rocprofiler_assign_callback_thread()

◆ rocprofiler_at_internal_thread_create()

◆ rocprofiler_create_callback_thread()