Thread. More...

Data Structures
struct	spdk_thread_stats

Macros
#define	SPDK_IO_CHANNEL_STRUCT_SIZE 96

#define	SPDK_DEFAULT_MSG_MEMPOOL_SIZE (262144 - 1)

#define	SPDK_POLLER_REGISTER(fn, arg, period_microseconds) spdk_poller_register_named(fn, arg, period_microseconds, #fn)

#define	SPDK_INTERRUPT_REGISTER(efd, fn, arg) spdk_interrupt_register(efd, fn, arg, #fn)

Typedefs
typedef int(*	spdk_new_thread_fn) (struct spdk_thread *thread)
	A function that is called each time a new thread is created. More...

typedef int(*	spdk_thread_op_fn) (struct spdk_thread *thread, enum spdk_thread_op op)
	Function to be called for SPDK thread operation.

typedef bool(*	spdk_thread_op_supported_fn) (enum spdk_thread_op op)
	Function to check whether the SPDK thread operation is supported.

typedef void(*	spdk_msg_fn) (void *ctx)
	A function that will be called on the target thread. More...

typedef void(*	spdk_thread_pass_msg) (spdk_msg_fn fn, void ctx, void thread_ctx)
	Function to be called to pass a message to a thread. More...

typedef int(*	spdk_poller_fn) (void *ctx)
	Callback function for a poller. More...

typedef struct spdk_poller (	spdk_start_poller) (void thread_ctx, spdk_poller_fn fn, void arg, uint64_t period_microseconds)
	Function to be called to start a poller for the thread. More...

typedef void(*	spdk_stop_poller) (struct spdk_poller poller, void thread_ctx)
	Function to be called to stop a poller. More...

typedef void(*	spdk_poller_set_interrupt_mode_cb) (struct spdk_poller poller, void cb_arg, bool interrupt_mode)
	Callback function to set poller into interrupt mode or back to poll mode. More...

typedef int(*	spdk_io_channel_create_cb) (void io_device, void ctx_buf)
	I/O channel creation callback. More...

typedef void(*	spdk_io_channel_destroy_cb) (void io_device, void ctx_buf)
	I/O channel destruction callback. More...

typedef void(*	spdk_io_device_unregister_cb) (void *io_device)
	I/O device unregister callback. More...

typedef void(*	spdk_channel_msg) (struct spdk_io_channel_iter *i)
	Called on the appropriate thread for each channel associated with io_device. More...

typedef void(*	spdk_channel_for_each_cpl) (struct spdk_io_channel_iter *i, int status)
	spdk_for_each_channel() callback. More...

typedef int(*	spdk_interrupt_fn) (void *ctx)
	Callback function registered for interrupt file descriptor. More...

Enumerations
enum	spdk_thread_poller_rc { SPDK_POLLER_IDLE , SPDK_POLLER_BUSY }
	Pollers should always return a value of this type indicating whether they did real work or not.

enum	spdk_thread_op { SPDK_THREAD_OP_NEW , SPDK_THREAD_OP_RESCHED }
	SPDK thread operation type.

enum	spdk_interrupt_event_types { SPDK_INTERRUPT_EVENT_IN = 0x001 , SPDK_INTERRUPT_EVENT_OUT = 0x004 , SPDK_INTERRUPT_EVENT_ET = 1u << 31 }

Functions
void	spdk_poller_register_interrupt (struct spdk_poller poller, spdk_poller_set_interrupt_mode_cb cb_fn, void cb_arg)
	Mark that the poller is capable of entering interrupt mode. More...

int	spdk_thread_lib_init (spdk_new_thread_fn new_thread_fn, size_t ctx_sz)
	Initialize the threading library. More...

int	spdk_thread_lib_init_ext (spdk_thread_op_fn thread_op_fn, spdk_thread_op_supported_fn thread_op_supported_fn, size_t ctx_sz, size_t msg_mempool_size)
	Initialize the threading library. More...

void	spdk_thread_lib_fini (void)
	Release all resources associated with this library.

struct spdk_thread *	spdk_thread_create (const char name, const struct spdk_cpuset cpumask)
	Creates a new SPDK thread object. More...

void	spdk_set_thread (struct spdk_thread *thread)
	Force the current system thread to act as if executing the given SPDK thread. More...

int	spdk_thread_exit (struct spdk_thread *thread)
	Mark the thread as exited, failing all future spdk_thread_send_msg(), spdk_poller_register(), and spdk_get_io_channel() calls. More...

bool	spdk_thread_is_exited (struct spdk_thread *thread)
	Returns whether the thread is marked as exited. More...

void	spdk_thread_destroy (struct spdk_thread *thread)
	Destroy a thread, releasing all of its resources. More...

void *	spdk_thread_get_ctx (struct spdk_thread *thread)
	Return a pointer to this thread's context. More...

struct spdk_cpuset *	spdk_thread_get_cpumask (struct spdk_thread *thread)
	Get the thread's cpumask. More...

int	spdk_thread_set_cpumask (struct spdk_cpuset *cpumask)
	Set the current thread's cpumask to the specified value. More...

struct spdk_thread *	spdk_thread_get_from_ctx (void *ctx)
	Return the thread object associated with the context handle previously obtained by calling spdk_thread_get_ctx(). More...

int	spdk_thread_poll (struct spdk_thread *thread, uint32_t max_msgs, uint64_t now)
	Perform one iteration worth of processing on the thread. More...

uint64_t	spdk_thread_next_poller_expiration (struct spdk_thread *thread)
	Return the number of ticks until the next timed poller would expire. More...

int	spdk_thread_has_active_pollers (struct spdk_thread *thread)
	Returns whether there are any active pollers (pollers for which period_microseconds equals 0) registered to be run on the thread. More...

bool	spdk_thread_has_pollers (struct spdk_thread *thread)
	Returns whether there are any pollers registered to be run on the thread. More...

bool	spdk_thread_is_idle (struct spdk_thread *thread)
	Returns whether there are scheduled operations to be run on the thread. More...

uint32_t	spdk_thread_get_count (void)
	Get count of allocated threads.

struct spdk_thread *	spdk_get_thread (void)
	Get a handle to the current thread. More...

const char *	spdk_thread_get_name (const struct spdk_thread *thread)
	Get a thread's name. More...

uint64_t	spdk_thread_get_id (const struct spdk_thread *thread)
	Get a thread's ID. More...

struct spdk_thread *	spdk_thread_get_by_id (uint64_t id)
	Get the thread by the ID. More...

int	spdk_thread_get_stats (struct spdk_thread_stats *stats)
	Get statistics about the current thread. More...

uint64_t	spdk_thread_get_last_tsc (struct spdk_thread *thread)
	Return the TSC value from the end of the last time this thread was polled. More...

int	spdk_thread_send_msg (const struct spdk_thread thread, spdk_msg_fn fn, void ctx)
	Send a message to the given thread. More...

int	spdk_thread_send_critical_msg (struct spdk_thread *thread, spdk_msg_fn fn)
	Send a message to the given thread. More...

static int	spdk_thread_exec_msg (const struct spdk_thread thread, spdk_msg_fn fn, void ctx)
	Run the msg callback on the given thread. More...

void	spdk_for_each_thread (spdk_msg_fn fn, void *ctx, spdk_msg_fn cpl)
	Send a message to each thread, serially. More...

void	spdk_thread_set_interrupt_mode (bool enable_interrupt)
	Set current spdk_thread into interrupt mode or back to poll mode. More...

struct spdk_poller *	spdk_poller_register (spdk_poller_fn fn, void *arg, uint64_t period_microseconds)
	Register a poller on the current thread. More...

struct spdk_poller *	spdk_poller_register_named (spdk_poller_fn fn, void arg, uint64_t period_microseconds, const char name)
	Register a poller on the current thread with arbitrary name. More...

void	spdk_poller_unregister (struct spdk_poller **ppoller)
	Unregister a poller on the current thread. More...

void	spdk_poller_pause (struct spdk_poller *poller)
	Pause a poller on the current thread. More...

void	spdk_poller_resume (struct spdk_poller *poller)
	Resume a poller on the current thread. More...

void	spdk_io_device_register (void io_device, spdk_io_channel_create_cb create_cb, spdk_io_channel_destroy_cb destroy_cb, uint32_t ctx_size, const char name)
	Register the opaque io_device context as an I/O device. More...

void	spdk_io_device_unregister (void *io_device, spdk_io_device_unregister_cb unregister_cb)
	Unregister the opaque io_device context as an I/O device. More...

struct spdk_io_channel *	spdk_get_io_channel (void *io_device)
	Get an I/O channel for the specified io_device to be used by the calling thread. More...

void	spdk_put_io_channel (struct spdk_io_channel *ch)
	Release a reference to an I/O channel. More...

static void *	spdk_io_channel_get_ctx (struct spdk_io_channel *ch)
	Get the context buffer associated with an I/O channel. More...

struct spdk_io_channel *	spdk_io_channel_from_ctx (void *ctx)
	Get I/O channel from the context buffer. More...

struct spdk_thread *	spdk_io_channel_get_thread (struct spdk_io_channel *ch)
	Get the thread associated with an I/O channel. More...

void	spdk_for_each_channel (void io_device, spdk_channel_msg fn, void ctx, spdk_channel_for_each_cpl cpl)
	Call 'fn' on each channel associated with io_device. More...

void *	spdk_io_channel_iter_get_io_device (struct spdk_io_channel_iter *i)
	Get io_device from the I/O channel iterator. More...

struct spdk_io_channel *	spdk_io_channel_iter_get_channel (struct spdk_io_channel_iter *i)
	Get I/O channel from the I/O channel iterator. More...

void *	spdk_io_channel_iter_get_ctx (struct spdk_io_channel_iter *i)
	Get context buffer from the I/O channel iterator. More...

void *	spdk_io_channel_get_io_device (struct spdk_io_channel *ch)
	Get the io_device for the specified I/O channel. More...

void	spdk_for_each_channel_continue (struct spdk_io_channel_iter *i, int status)
	Helper function to iterate all channels for spdk_for_each_channel(). More...

struct spdk_interrupt *	spdk_interrupt_register (int efd, spdk_interrupt_fn fn, void arg, const char name)
	Register an spdk_interrupt on the current thread. More...

void	spdk_interrupt_unregister (struct spdk_interrupt **pintr)
	Unregister an spdk_interrupt on the current thread. More...

int	spdk_interrupt_set_event_types (struct spdk_interrupt *intr, enum spdk_interrupt_event_types event_types)
	Change the event_types associated with the spdk_interrupt on the current thread. More...

int	spdk_thread_get_interrupt_fd (struct spdk_thread *thread)
	Return a file descriptor that becomes ready whenever any of the registered interrupt file descriptors are ready. More...

int	spdk_interrupt_mode_enable (void)
	Set SPDK run as event driven mode. More...

bool	spdk_interrupt_mode_is_enabled (void)
	Reports whether interrupt mode is set. More...

Detailed Description

Thread.

Typedef Documentation

◆ spdk_channel_for_each_cpl

typedef void(* spdk_channel_for_each_cpl) (struct spdk_io_channel_iter *i, int status)

spdk_for_each_channel() callback.

Parameters

i	I/O channel iterator.
status	0 if it completed successfully, or negative errno if it failed.

◆ spdk_channel_msg

typedef void(* spdk_channel_msg) (struct spdk_io_channel_iter *i)

Called on the appropriate thread for each channel associated with io_device.

Parameters

i	I/O channel iterator.

◆ spdk_interrupt_fn

typedef int(* spdk_interrupt_fn) (void *ctx)

Callback function registered for interrupt file descriptor.

Parameters

ctx	Context passed as arg to spdk_interrupt_register().

Returns: 0 to indicate that interrupt took place but no events were found; positive to indicate that interrupt took place and some events were processed; negative if no event information is provided.

◆ spdk_io_channel_create_cb

typedef int(* spdk_io_channel_create_cb) (void *io_device, void *ctx_buf)

I/O channel creation callback.

Parameters

io_device	I/O device associated with this channel.
ctx_buf	Context for the I/O device.

◆ spdk_io_channel_destroy_cb

typedef void(* spdk_io_channel_destroy_cb) (void *io_device, void *ctx_buf)

I/O channel destruction callback.

Parameters

io_device	I/O device associated with this channel.
ctx_buf	Context for the I/O device.

◆ spdk_io_device_unregister_cb

typedef void(* spdk_io_device_unregister_cb) (void *io_device)

I/O device unregister callback.

Parameters

io_device Unregistered I/O device.

◆ spdk_msg_fn

typedef void(* spdk_msg_fn) (void *ctx)

A function that will be called on the target thread.

Parameters

ctx	Context passed as arg to spdk_thread_pass_msg().

◆ spdk_new_thread_fn

typedef int(* spdk_new_thread_fn) (struct spdk_thread *thread)

A function that is called each time a new thread is created.

The implementor of this function should frequently call spdk_thread_poll() on the thread provided.

Parameters

thread The new spdk_thread.

◆ spdk_poller_fn

typedef int(* spdk_poller_fn) (void *ctx)

Callback function for a poller.

Parameters

ctx	Context passed as arg to spdk_poller_register().

Returns: value of type enum spdk_thread_poller_rc (ex: SPDK_POLLER_IDLE if no work was done or SPDK_POLLER_BUSY if work was done.)

◆ spdk_poller_set_interrupt_mode_cb

typedef void(* spdk_poller_set_interrupt_mode_cb) (struct spdk_poller *poller, void *cb_arg, bool interrupt_mode)

Callback function to set poller into interrupt mode or back to poll mode.

Parameters

poller	Poller to set interrupt or poll mode.
cb_arg	Argument passed to the callback function.
interrupt_mode	Set interrupt mode for true, or poll mode for false

◆ spdk_start_poller

typedef struct spdk_poller*(* spdk_start_poller) (void *thread_ctx, spdk_poller_fn fn, void *arg, uint64_t period_microseconds)

Function to be called to start a poller for the thread.

Parameters

thread_ctx	Context for the thread.
fn	Callback function for a poller.
arg	Argument passed to callback.
period_microseconds	Polling period in microseconds.

Returns: a pointer to the poller on success, or NULL on failure.

◆ spdk_stop_poller

typedef void(* spdk_stop_poller) (struct spdk_poller *poller, void *thread_ctx)

Function to be called to stop a poller.

Parameters

poller	Poller to stop.
thread_ctx	Context for the thread.

◆ spdk_thread_pass_msg

typedef void(* spdk_thread_pass_msg) (spdk_msg_fn fn, void *ctx, void *thread_ctx)

Function to be called to pass a message to a thread.

Parameters

fn	Callback function for a thread.
ctx	Context passed to fn.
thread_ctx	Context for the thread.

Function Documentation

◆ spdk_for_each_channel()

void spdk_for_each_channel	(	void *	io_device,
		spdk_channel_msg	fn,
		void *	ctx,
		spdk_channel_for_each_cpl	cpl
	)

Call 'fn' on each channel associated with io_device.

This happens asynchronously, so fn may be called after spdk_for_each_channel returns. 'fn' will be called for each channel serially, such that two calls to 'fn' will not overlap in time. After 'fn' has been called, call spdk_for_each_channel_continue() to continue iterating.

Parameters

io_device	'fn' will be called on each channel associated with this io_device.
fn	Called on the appropriate thread for each channel associated with io_device.
ctx	Context buffer registered to spdk_io_channel_iter that can be obtained form the function spdk_io_channel_iter_get_ctx().
cpl	Called on the thread that spdk_for_each_channel was initially called from when 'fn' has been called on each channel.

◆ spdk_for_each_channel_continue()

void spdk_for_each_channel_continue	(	struct spdk_io_channel_iter *	i,
		int	status
	)

Helper function to iterate all channels for spdk_for_each_channel().

Parameters

i	I/O channel iterator.
status	Status for the I/O channel iterator; for non 0 status remaining iterations are terminated.

◆ spdk_for_each_thread()

void spdk_for_each_thread	(	spdk_msg_fn	fn,
		void *	ctx,
		spdk_msg_fn	cpl
	)

Send a message to each thread, serially.

The message is sent asynchronously - i.e. spdk_for_each_thread will return prior to fn being called on each thread.

Parameters

fn	This is the function that will be called on each thread.
ctx	This context will be passed to fn when called.
cpl	This will be called on the originating thread after `fn` has been called on each thread.

◆ spdk_get_io_channel()

struct spdk_io_channel* spdk_get_io_channel ( void * io_device )

Get an I/O channel for the specified io_device to be used by the calling thread.

The io_device context pointer specified must have previously been registered using spdk_io_device_register(). If an existing I/O channel does not exist yet for the given io_device on the calling thread, it will allocate an I/O channel and invoke the create_cb function pointer specified in spdk_io_device_register(). If an I/O channel already exists for the given io_device on the calling thread, its reference is returned rather than creating a new I/O channel.

Parameters

io_device The pointer to io_device context.

Returns: a pointer to the I/O channel for this device on success or NULL on failure.

◆ spdk_get_thread()

struct spdk_thread* spdk_get_thread ( void )

Get a handle to the current thread.

This handle may be passed to other threads and used as the target of spdk_thread_send_msg().

See also: spdk_io_channel_get_thread()

Returns: a pointer to the current thread on success or NULL on failure.

◆ spdk_interrupt_mode_enable()

int spdk_interrupt_mode_enable ( void )

Set SPDK run as event driven mode.

Returns: 0 on success or -errno on failure

◆ spdk_interrupt_mode_is_enabled()

bool spdk_interrupt_mode_is_enabled ( void )

Reports whether interrupt mode is set.

Returns: True if interrupt mode is set, false otherwise.

◆ spdk_interrupt_register()

struct spdk_interrupt* spdk_interrupt_register	(	int	efd,
		spdk_interrupt_fn	fn,
		void *	arg,
		const char *	name
	)

Register an spdk_interrupt on the current thread.

The provided function will be called any time the associated file descriptor is written to.

Parameters

efd	File descriptor of the spdk_interrupt.
fn	Called each time there are events in spdk_interrupt.
arg	Function argument for fn.
name	Human readable name for the spdk_interrupt. Pointer of the spdk_interrupt name is set if NULL.

Returns: a pointer to the spdk_interrupt registered on the current thread on success or NULL on failure.

◆ spdk_interrupt_set_event_types()

int spdk_interrupt_set_event_types	(	struct spdk_interrupt *	intr,
		enum spdk_interrupt_event_types	event_types
	)

Change the event_types associated with the spdk_interrupt on the current thread.

Parameters

intr	The pointer to the spdk_interrupt registered on the current thread.
event_types	New event_types for the spdk_interrupt.

Returns: 0 if success or -errno if failed.

◆ spdk_interrupt_unregister()

void spdk_interrupt_unregister ( struct spdk_interrupt ** pintr )

Unregister an spdk_interrupt on the current thread.

Parameters

pintr The spdk_interrupt to unregister.

◆ spdk_io_channel_from_ctx()

struct spdk_io_channel* spdk_io_channel_from_ctx ( void * ctx )

Get I/O channel from the context buffer.

This is the inverse of spdk_io_channel_get_ctx().

Parameters

ctx	The pointer to the context buffer.

Returns: a pointer to the I/O channel associated with the context buffer.

◆ spdk_io_channel_get_ctx()

static void* spdk_io_channel_get_ctx ( struct spdk_io_channel * ch )

inlinestatic

Get the context buffer associated with an I/O channel.

Parameters

ch	I/O channel.

Returns: a pointer to the context buffer.

◆ spdk_io_channel_get_io_device()

void* spdk_io_channel_get_io_device ( struct spdk_io_channel * ch )

Get the io_device for the specified I/O channel.

Parameters

ch	I/O channel.

Returns: a pointer to the io_device for the I/O channel

◆ spdk_io_channel_get_thread()

struct spdk_thread* spdk_io_channel_get_thread ( struct spdk_io_channel * ch )

Get the thread associated with an I/O channel.

Parameters

ch	I/O channel.

Returns: a pointer to the thread associated with the I/O channel

◆ spdk_io_channel_iter_get_channel()

struct spdk_io_channel* spdk_io_channel_iter_get_channel ( struct spdk_io_channel_iter * i )

Get I/O channel from the I/O channel iterator.

Parameters

i	I/O channel iterator.

Returns: a pointer to the I/O channel.

◆ spdk_io_channel_iter_get_ctx()

void* spdk_io_channel_iter_get_ctx ( struct spdk_io_channel_iter * i )

Get context buffer from the I/O channel iterator.

Parameters

i	I/O channel iterator.

Returns: a pointer to the context buffer.

◆ spdk_io_channel_iter_get_io_device()

void* spdk_io_channel_iter_get_io_device ( struct spdk_io_channel_iter * i )

Get io_device from the I/O channel iterator.

Parameters

i	I/O channel iterator.

Returns: a pointer to the io_device.

◆ spdk_io_device_register()

void spdk_io_device_register	(	void *	io_device,
		spdk_io_channel_create_cb	create_cb,
		spdk_io_channel_destroy_cb	destroy_cb,
		uint32_t	ctx_size,
		const char *	name
	)

Register the opaque io_device context as an I/O device.

After an I/O device is registered, it can return I/O channels using the spdk_get_io_channel() function.

Parameters

io_device	The pointer to io_device context.
create_cb	Callback function invoked to allocate any resources required for a new I/O channel.
destroy_cb	Callback function invoked to release the resources for an I/O channel.
ctx_size	The size of the context buffer allocated to store references to allocated I/O channel resources.
name	A string name for the device used only for debugging. Optional - may be NULL.

◆ spdk_io_device_unregister()

void spdk_io_device_unregister	(	void *	io_device,
		spdk_io_device_unregister_cb	unregister_cb
	)

Unregister the opaque io_device context as an I/O device.

The actual unregistration might be deferred until all active I/O channels are destroyed.

Parameters

io_device	The pointer to io_device context.
unregister_cb	An optional callback function invoked to release any references to this I/O device.

◆ spdk_poller_pause()

void spdk_poller_pause ( struct spdk_poller * poller )

Pause a poller on the current thread.

The poller is not run until it is resumed with spdk_poller_resume(). It is perfectly fine to pause an already paused poller.

Parameters

poller The poller to pause.

◆ spdk_poller_register()

struct spdk_poller* spdk_poller_register	(	spdk_poller_fn	fn,
		void *	arg,
		uint64_t	period_microseconds
	)

Register a poller on the current thread.

The poller can be unregistered by calling spdk_poller_unregister().

Parameters

fn	This function will be called every `period_microseconds`.
arg	Argument passed to fn.
period_microseconds	How often to call `fn`. If 0, call `fn` as often as possible.

Returns: a pointer to the poller registered on the current thread on success or NULL on failure.

◆ spdk_poller_register_interrupt()

void spdk_poller_register_interrupt	(	struct spdk_poller *	poller,
		spdk_poller_set_interrupt_mode_cb	cb_fn,
		void *	cb_arg
	)

Mark that the poller is capable of entering interrupt mode.

When registering the poller set interrupt callback, the callback will get executed immediately if its spdk_thread is in the interrupt mode.

Parameters

poller	The poller to register callback function.
cb_fn	Callback function called when the poller must transition into or out of interrupt mode
cb_arg	Argument passed to the callback function.

◆ spdk_poller_register_named()

struct spdk_poller* spdk_poller_register_named	(	spdk_poller_fn	fn,
		void *	arg,
		uint64_t	period_microseconds,
		const char *	name
	)

Register a poller on the current thread with arbitrary name.

The poller can be unregistered by calling spdk_poller_unregister().

Parameters

fn	This function will be called every `period_microseconds`.
arg	Argument passed to fn.
period_microseconds	How often to call `fn`. If 0, call `fn` as often as possible.
name	Human readable name for the poller. Pointer of the poller function name is set if NULL.

Returns: a pointer to the poller registered on the current thread on success or NULL on failure.

◆ spdk_poller_resume()

void spdk_poller_resume ( struct spdk_poller * poller )

Resume a poller on the current thread.

Resumes a poller paused with spdk_poller_pause(). It is perfectly fine to resume an unpaused poller.

Parameters

poller The poller to resume.

◆ spdk_poller_unregister()

void spdk_poller_unregister ( struct spdk_poller ** ppoller )

Unregister a poller on the current thread.

Parameters

ppoller The poller to unregister.

◆ spdk_put_io_channel()

void spdk_put_io_channel ( struct spdk_io_channel * ch )

Release a reference to an I/O channel.

This happens asynchronously.

This must be called on the same thread that called spdk_get_io_channel() for the specified I/O channel. If this releases the last reference to the I/O channel, The destroy_cb function specified in spdk_io_device_register() will be invoked to release any associated resources.

Parameters

ch	I/O channel to release a reference.

◆ spdk_set_thread()

void spdk_set_thread ( struct spdk_thread * thread )

Force the current system thread to act as if executing the given SPDK thread.

Parameters

thread The thread to set.

◆ spdk_thread_create()

struct spdk_thread* spdk_thread_create	(	const char *	name,
		const struct spdk_cpuset *	cpumask
	)

Creates a new SPDK thread object.

Parameters

name	Human-readable name for the thread; can be retrieved with spdk_thread_get_name(). The string is copied, so the pointed-to data only needs to be valid during the spdk_thread_create() call. May be NULL to specify no name.
cpumask	Optional mask of CPU cores on which to schedule this thread. This is only a suggestion to the scheduler. The value is copied, so cpumask may be released when this function returns. May be NULL if no mask is required.

Returns: a pointer to the allocated thread on success or NULL on failure..

◆ spdk_thread_destroy()

void spdk_thread_destroy ( struct spdk_thread * thread )

Destroy a thread, releasing all of its resources.

May only be called on a thread previously marked as exited.

Parameters

thread The thread to destroy.

◆ spdk_thread_exec_msg()

static int spdk_thread_exec_msg	(	const struct spdk_thread *	thread,
		spdk_msg_fn	fn,
		void *	ctx
	)

inlinestatic

Run the msg callback on the given thread.

If this happens to be the current thread, the callback is executed immediately; otherwise a message is sent to the thread, and it's run asynchronously.

Parameters

thread	The target thread.
fn	This function will be called on the given thread.
ctx	This context will be passed to fn when called.

Returns: 0 on success; -ENOMEM if the message could not be allocated; -EIO if the message could not be sent to the destination thread

◆ spdk_thread_exit()

int spdk_thread_exit ( struct spdk_thread * thread )

Mark the thread as exited, failing all future spdk_thread_send_msg(), spdk_poller_register(), and spdk_get_io_channel() calls.

May only be called within an spdk poller or message.

All I/O channel references associated with the thread must be released using spdk_put_io_channel(), and all active pollers associated with the thread should be unregistered using spdk_poller_unregister(), prior to calling this function. This function will complete these processing. The completion can be queried by spdk_thread_is_exited().

Parameters

thread The thread to destroy.

Returns: always 0. (return value was deprecated but keep it for ABI compatibility.)

◆ spdk_thread_get_by_id()

struct spdk_thread* spdk_thread_get_by_id ( uint64_t id )

Get the thread by the ID.

Parameters

id	ID of the thread.

Returns: Thread whose ID matches or NULL otherwise.

◆ spdk_thread_get_cpumask()

struct spdk_cpuset* spdk_thread_get_cpumask ( struct spdk_thread * thread )

Get the thread's cpumask.

Parameters

thread The thread to get the cpumask for.

Returns: cpuset pointer

◆ spdk_thread_get_ctx()

void* spdk_thread_get_ctx ( struct spdk_thread * thread )

Return a pointer to this thread's context.

Parameters

thread The thread on which to get the context.

Returns: a pointer to the per-thread context, or NULL if there is no per-thread context.

◆ spdk_thread_get_from_ctx()

struct spdk_thread* spdk_thread_get_from_ctx ( void * ctx )

Return the thread object associated with the context handle previously obtained by calling spdk_thread_get_ctx().

Parameters

ctx	A context previously obtained by calling spdk_thread_get_ctx()

Returns: The associated thread.

◆ spdk_thread_get_id()

uint64_t spdk_thread_get_id ( const struct spdk_thread * thread )

Get a thread's ID.

Parameters

thread Thread to query.

Returns: the ID of the thread..

◆ spdk_thread_get_interrupt_fd()

int spdk_thread_get_interrupt_fd ( struct spdk_thread * thread )

Return a file descriptor that becomes ready whenever any of the registered interrupt file descriptors are ready.

Parameters

thread The thread to get.

Returns: The spdk_interrupt fd of thread itself.

◆ spdk_thread_get_last_tsc()

uint64_t spdk_thread_get_last_tsc ( struct spdk_thread * thread )

Return the TSC value from the end of the last time this thread was polled.

Parameters

thread Thread to query.

Returns: TSC value from the end of the last time this thread was polled.

◆ spdk_thread_get_name()

const char* spdk_thread_get_name ( const struct spdk_thread * thread )

Get a thread's name.

Parameters

thread Thread to query.

Returns: the name of the thread.

◆ spdk_thread_get_stats()

int spdk_thread_get_stats ( struct spdk_thread_stats * stats )

Get statistics about the current thread.

Copy cumulative thread stats values to the provided thread stats structure.

Parameters

stats User's thread_stats structure.

◆ spdk_thread_has_active_pollers()

int spdk_thread_has_active_pollers ( struct spdk_thread * thread )

Returns whether there are any active pollers (pollers for which period_microseconds equals 0) registered to be run on the thread.

Parameters

thread The thread to check.

Returns: 1 if there is at least one active poller, 0 otherwise.

◆ spdk_thread_has_pollers()

bool spdk_thread_has_pollers ( struct spdk_thread * thread )

Returns whether there are any pollers registered to be run on the thread.

Parameters

thread The thread to check.

Returns: true if there is any active poller, false otherwise.

◆ spdk_thread_is_exited()

bool spdk_thread_is_exited ( struct spdk_thread * thread )

Returns whether the thread is marked as exited.

Parameters

thread The thread to query.

Returns: true if marked as exited, false otherwise.

◆ spdk_thread_is_idle()

bool spdk_thread_is_idle ( struct spdk_thread * thread )

Returns whether there are scheduled operations to be run on the thread.

Parameters

thread The thread to check.

Returns: true if there are no scheduled operations, false otherwise.

◆ spdk_thread_lib_init()

int spdk_thread_lib_init	(	spdk_new_thread_fn	new_thread_fn,
		size_t	ctx_sz
	)

Initialize the threading library.

Must be called once prior to allocating any threads.

Parameters

new_thread_fn	Called each time a new SPDK thread is created. The implementor is expected to frequently call spdk_thread_poll() on the provided thread.
ctx_sz	For each thread allocated, an additional region of memory of size ctx_size will also be allocated, for use by the thread scheduler. A pointer to this region may be obtained by calling spdk_thread_get_ctx().

Returns: 0 on success. Negated errno on failure.

◆ spdk_thread_lib_init_ext()

int spdk_thread_lib_init_ext	(	spdk_thread_op_fn	thread_op_fn,
		spdk_thread_op_supported_fn	thread_op_supported_fn,
		size_t	ctx_sz,
		size_t	msg_mempool_size
	)

Initialize the threading library.

Must be called once prior to allocating any threads

Both thread_op_fn and thread_op_type_supported_fn have to be specified or not specified together.

Parameters

thread_op_fn	Called for SPDK thread operation.
thread_op_supported_fn	Called to check whether the SPDK thread operation is supported.
ctx_sz	For each thread allocated, for use by the thread scheduler. A pointer to this region may be obtained by calling spdk_thread_get_ctx().
msg_mempool_size	Size of the allocated spdk_msg_mempool.

Returns: 0 on success. Negated errno on failure.

◆ spdk_thread_next_poller_expiration()

uint64_t spdk_thread_next_poller_expiration ( struct spdk_thread * thread )

Return the number of ticks until the next timed poller would expire.

Timed pollers are pollers for which period_microseconds is greater than 0.

Parameters

thread The thread to check poller expiration times on

Returns: Number of ticks. If no timed pollers, return 0.

◆ spdk_thread_poll()

int spdk_thread_poll	(	struct spdk_thread *	thread,
		uint32_t	max_msgs,
		uint64_t	now
	)

Perform one iteration worth of processing on the thread.

This includes both expired and continuous pollers as well as messages. If the thread has exited, return immediately.

Parameters

thread	The thread to process
max_msgs	The maximum number of messages that will be processed. Use 0 to process the default number of messages (8).
now	The current time, in ticks. Optional. If 0 is passed, this function will call spdk_get_ticks() to get the current time. The current time is used as start time and this function will call spdk_get_ticks() at its end to know end time to measure run time of this function.

Returns: 1 if work was done. 0 if no work was done.

◆ spdk_thread_send_critical_msg()

int spdk_thread_send_critical_msg	(	struct spdk_thread *	thread,
		spdk_msg_fn	fn
	)

Send a message to the given thread.

Only one critical message can be outstanding at the same time. It's intended to use this function in any cases that might interrupt the execution of the application, such as signal handlers.

The message will be sent asynchronously - i.e. spdk_thread_send_critical_msg will always return prior to fn being called.

Parameters

thread	The target thread.
fn	This function will be called on the given thread.

Returns: 0 on success; -EIO if the message could not be sent to the destination thread, due to an already outstanding critical message

◆ spdk_thread_send_msg()

int spdk_thread_send_msg	(	const struct spdk_thread *	thread,
		spdk_msg_fn	fn,
		void *	ctx
	)

Send a message to the given thread.

The message will be sent asynchronously - i.e. spdk_thread_send_msg will always return prior to fn being called.

Parameters

thread	The target thread.
fn	This function will be called on the given thread.
ctx	This context will be passed to fn when called.

Returns: 0 on success; -ENOMEM if the message could not be allocated; -EIO if the message could not be sent to the destination thread

◆ spdk_thread_set_cpumask()

int spdk_thread_set_cpumask ( struct spdk_cpuset * cpumask )

Set the current thread's cpumask to the specified value.

The thread may be rescheduled to one of the CPUs specified in the cpumask.

This API requires SPDK thread operation supports SPDK_THREAD_OP_RESCHED.

Parameters

cpumask The new cpumask for the thread.

Returns: 0 on success, negated errno otherwise.

◆ spdk_thread_set_interrupt_mode()

void spdk_thread_set_interrupt_mode ( bool enable_interrupt )

Set current spdk_thread into interrupt mode or back to poll mode.

Only valid when thread interrupt facility is enabled by spdk_interrupt_mode_enable().

Parameters

enable_interrupt Set interrupt mode for true, or poll mode for false

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ spdk_channel_for_each_cpl

◆ spdk_channel_msg

◆ spdk_interrupt_fn

◆ spdk_io_channel_create_cb

◆ spdk_io_channel_destroy_cb

◆ spdk_io_device_unregister_cb

◆ spdk_msg_fn

◆ spdk_new_thread_fn

◆ spdk_poller_fn

◆ spdk_poller_set_interrupt_mode_cb

◆ spdk_start_poller

◆ spdk_stop_poller

◆ spdk_thread_pass_msg

Function Documentation

◆ spdk_for_each_channel()

◆ spdk_for_each_channel_continue()

◆ spdk_for_each_thread()

◆ spdk_get_io_channel()

◆ spdk_get_thread()

◆ spdk_interrupt_mode_enable()

◆ spdk_interrupt_mode_is_enabled()

◆ spdk_interrupt_register()

◆ spdk_interrupt_set_event_types()

◆ spdk_interrupt_unregister()

◆ spdk_io_channel_from_ctx()

◆ spdk_io_channel_get_ctx()

◆ spdk_io_channel_get_io_device()

◆ spdk_io_channel_get_thread()

◆ spdk_io_channel_iter_get_channel()

◆ spdk_io_channel_iter_get_ctx()

◆ spdk_io_channel_iter_get_io_device()

◆ spdk_io_device_register()

◆ spdk_io_device_unregister()

◆ spdk_poller_pause()

◆ spdk_poller_register()

◆ spdk_poller_register_interrupt()

◆ spdk_poller_register_named()

◆ spdk_poller_resume()

◆ spdk_poller_unregister()

◆ spdk_put_io_channel()

◆ spdk_set_thread()

◆ spdk_thread_create()

◆ spdk_thread_destroy()

◆ spdk_thread_exec_msg()

◆ spdk_thread_exit()

◆ spdk_thread_get_by_id()

◆ spdk_thread_get_cpumask()

◆ spdk_thread_get_ctx()

◆ spdk_thread_get_from_ctx()

◆ spdk_thread_get_id()

◆ spdk_thread_get_interrupt_fd()

◆ spdk_thread_get_last_tsc()

◆ spdk_thread_get_name()

◆ spdk_thread_get_stats()

◆ spdk_thread_has_active_pollers()

◆ spdk_thread_has_pollers()

◆ spdk_thread_is_exited()

◆ spdk_thread_is_idle()

◆ spdk_thread_lib_init()

◆ spdk_thread_lib_init_ext()

◆ spdk_thread_next_poller_expiration()

◆ spdk_thread_poll()

◆ spdk_thread_send_critical_msg()

◆ spdk_thread_send_msg()

◆ spdk_thread_set_cpumask()

◆ spdk_thread_set_interrupt_mode()