Thread. More...

Data Structures
struct	spdk_thread_stats

struct	spdk_spinlock
	A spinlock augmented with safety checks for use with SPDK. More...

struct	spdk_iobuf_opts

struct	spdk_iobuf_pool_stats

struct	spdk_iobuf_module_stats

struct	spdk_iobuf_entry
	iobuf queue entry More...

struct	spdk_iobuf_buffer

struct	spdk_iobuf_pool

struct	spdk_iobuf_channel
	iobuf channel More...

Macros
#define	SPDK_IO_CHANNEL_STRUCT_SIZE 96

#define	SPDK_MSG_MEMPOOL_CACHE_SIZE 1024
	Message memory pool size definitions.

#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)

#define	SPDK_INTERRUPT_REGISTER_FOR_EVENTS(efd, events, fn, arg) spdk_interrupt_register_for_events(efd, events, 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.

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.

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.

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

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.

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

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

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

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

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

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

typedef void(*	spdk_iobuf_get_cb) (struct spdk_iobuf_entry entry, void buf)

typedef void(*	spdk_iobuf_finish_cb) (void *cb_arg)

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.

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

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.

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.

struct spdk_thread *	spdk_thread_get_app_thread (void)
	Return the app thread.

bool	spdk_thread_is_app_thread (struct spdk_thread *thread)
	Check if the specified spdk_thread is the app thread.

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

void	spdk_thread_bind (struct spdk_thread *thread, bool bind)
	Bind or unbind spdk_thread to its current CPU core.

bool	spdk_thread_is_bound (struct spdk_thread *thread)
	Returns whether the thread is bound to its current CPU core.

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.

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

bool	spdk_thread_is_running (struct spdk_thread *thread)
	Returns whether the thread is still running.

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

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

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

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

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().

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

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

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.

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

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

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.

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

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

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

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

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.

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

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

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.

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

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

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

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.

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

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

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

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.

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.

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.

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

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

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

struct spdk_thread *	spdk_io_channel_get_thread (struct spdk_io_channel *ch)
	Get the thread associated with an I/O 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.

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

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.

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

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

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().

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.

struct spdk_interrupt *	spdk_interrupt_register_for_events (int efd, uint32_t events, spdk_interrupt_fn fn, void arg, const char name)
	Register an spdk_interrupt with specific event types on the current thread.

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

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.

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.

struct spdk_fd_group *	spdk_thread_get_interrupt_fd_group (struct spdk_thread *thread)
	Return an fd_group that becomes ready whenever any of the registered interrupt file descriptors are ready.

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

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

void	spdk_spin_init (struct spdk_spinlock *sspin)
	Initialize an spdk_spinlock.

void	spdk_spin_destroy (struct spdk_spinlock *sspin)
	Destroy an spdk_spinlock.

void	spdk_spin_lock (struct spdk_spinlock *sspin)
	Lock an SPDK spin lock.

void	spdk_spin_unlock (struct spdk_spinlock *sspin)
	Unlock an SPDK spinlock.

bool	spdk_spin_held (struct spdk_spinlock *sspin)
	Determine if the caller holds this SPDK spinlock.

typedef	STAILQ_HEAD (, spdk_iobuf_entry) spdk_iobuf_entry_stailq_t

typedef	STAILQ_HEAD (, spdk_iobuf_buffer) spdk_iobuf_buffer_stailq_t

int	spdk_iobuf_initialize (void)
	Initialize and allocate iobuf pools.

void	spdk_iobuf_finish (spdk_iobuf_finish_cb cb_fn, void *cb_arg)
	Clean up and free iobuf pools.

int	spdk_iobuf_set_opts (const struct spdk_iobuf_opts *opts)
	Set iobuf options.

void	spdk_iobuf_get_opts (struct spdk_iobuf_opts *opts, size_t opts_size)
	Get iobuf options.

Name of the module.
Unregister an iobuf pool user from a module. Returns 0 on success, negative errno otherwise.
typedef int(*	spdk_iobuf_for_each_entry_fn) (struct spdk_iobuf_channel ch, struct spdk_iobuf_entry entry, void *ctx)

typedef void(*	spdk_iobuf_get_stats_cb) (struct spdk_iobuf_module_stats modules, uint32_t num_modules, void cb_arg)

int	spdk_iobuf_register_module (const char *name)

int	spdk_iobuf_unregister_module (const char *name)

int	spdk_iobuf_channel_init (struct spdk_iobuf_channel ch, const char name, uint32_t small_cache_size, uint32_t large_cache_size)
	Initialize an iobuf channel.

void	spdk_iobuf_channel_fini (struct spdk_iobuf_channel *ch)
	Release resources tied to an iobuf channel.

int	spdk_iobuf_for_each_entry (struct spdk_iobuf_channel ch, struct spdk_iobuf_pool pool, spdk_iobuf_for_each_entry_fn cb_fn, void *cb_ctx)
	Iterate over all entries on a given queue and execute a callback on those that were requested using `ch`.

void	spdk_iobuf_entry_abort (struct spdk_iobuf_channel ch, struct spdk_iobuf_entry entry, uint64_t len)
	Abort an outstanding request waiting for a buffer.

void *	spdk_iobuf_get (struct spdk_iobuf_channel ch, uint64_t len, struct spdk_iobuf_entry entry, spdk_iobuf_get_cb cb_fn)
	Get a buffer from the iobuf pool.

void	spdk_iobuf_put (struct spdk_iobuf_channel ch, void buf, uint64_t len)
	Release a buffer back to the iobuf pool.

int	spdk_iobuf_get_stats (spdk_iobuf_get_stats_cb cb_fn, void *cb_arg)
	Get iobuf statistics.

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 implementer 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_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 a SPDK_INTERRUPT_EVENT_IN event triggers on the associated file descriptor.

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_register_for_events()

struct spdk_interrupt * spdk_interrupt_register_for_events	(	int	efd,
		uint32_t	events,
		spdk_interrupt_fn	fn,
		void *	arg,
		const char *	name )

Register an spdk_interrupt with specific event types on the current thread.

The provided function will be called any time one of specified event types triggers on the associated file descriptor. Event types argument is a bit mask composed by ORing together enum spdk_interrupt_event_types values.

Parameters

efd	File descriptor of the spdk_interrupt.
events	Event notification types.
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_iobuf_channel_fini()

void spdk_iobuf_channel_fini ( struct spdk_iobuf_channel * ch )

Release resources tied to an iobuf channel.

Parameters

ch	iobuf channel.

◆ spdk_iobuf_channel_init()

int spdk_iobuf_channel_init	(	struct spdk_iobuf_channel *	ch,
		const char *	name,
		uint32_t	small_cache_size,
		uint32_t	large_cache_size )

Initialize an iobuf channel.

Parameters

ch	iobuf channel to initialize.
name	Name of the module registered via `spdk_iobuf_register_module()`.
small_cache_size	Number of small buffers to be cached by this channel.
large_cache_size	Number of large buffers to be cached by this channel.

Returns: 0 on success, negative errno otherwise.

◆ spdk_iobuf_entry_abort()

void spdk_iobuf_entry_abort	(	struct spdk_iobuf_channel *	ch,
		struct spdk_iobuf_entry *	entry,
		uint64_t	len )

Abort an outstanding request waiting for a buffer.

Parameters

ch	iobuf channel on which the entry is waiting.
entry	Entry to remove from the wait queue.
len	Length of the requested buffer (must be the exact same value as specified in `spdk_iobuf_get()`.

◆ spdk_iobuf_finish()

void spdk_iobuf_finish	(	spdk_iobuf_finish_cb	cb_fn,
		void *	cb_arg )

Clean up and free iobuf pools.

Parameters

cb_fn	Callback to be executed once the clean up is completed.
cb_arg	Callback argument.

◆ spdk_iobuf_for_each_entry()

int spdk_iobuf_for_each_entry	(	struct spdk_iobuf_channel *	ch,
		struct spdk_iobuf_pool *	pool,
		spdk_iobuf_for_each_entry_fn	cb_fn,
		void *	cb_ctx )

Iterate over all entries on a given queue and execute a callback on those that were requested using ch.

The iteration is stopped if the callback returns non-zero status.

Parameters

ch	iobuf channel to iterate over.
pool	Pool to iterate over (`small` or `large`).
cb_fn	Callback to execute on each entry on the queue that was requested using `ch`.
cb_ctx	Argument passed to `cb_fn`.

Returns: status of the last callback.

◆ spdk_iobuf_get()

void * spdk_iobuf_get	(	struct spdk_iobuf_channel *	ch,
		uint64_t	len,
		struct spdk_iobuf_entry *	entry,
		spdk_iobuf_get_cb	cb_fn )

Get a buffer from the iobuf pool.

If no buffers are available and entry with cb_fn provided then the request is queued until a buffer becomes available.

Parameters

ch	iobuf channel.
len	Length of the buffer to retrieve. The user is responsible for making sure the length doesn't exceed large_bufsize.
entry	Wait queue entry (optional).
cb_fn	Callback to be executed once a buffer becomes available. If a buffer is available immediately, it is NOT executed. Mandatory only if entry provided.

Returns: pointer to a buffer or NULL if no buffers are currently available.

◆ spdk_iobuf_get_opts()

void spdk_iobuf_get_opts	(	struct spdk_iobuf_opts *	opts,
		size_t	opts_size )

Get iobuf options.

Parameters

opts	Output parameter for options.
opts_size	sizeof(*opts)

◆ spdk_iobuf_get_stats()

int spdk_iobuf_get_stats	(	spdk_iobuf_get_stats_cb	cb_fn,
		void *	cb_arg )

Get iobuf statistics.

Parameters

cb_fn	Callback to be executed once stats are gathered.
cb_arg	Argument passed to the callback function.

Returns: 0 on success, negative errno otherwise.

◆ spdk_iobuf_initialize()

int spdk_iobuf_initialize ( void )

Initialize and allocate iobuf pools.

Returns: 0 on success, negative errno otherwise.

◆ spdk_iobuf_put()

void spdk_iobuf_put	(	struct spdk_iobuf_channel *	ch,
		void *	buf,
		uint64_t	len )

Release a buffer back to the iobuf pool.

If there are outstanding requests waiting for a buffer, this buffer will be passed to one of them.

Parameters

ch	iobuf channel.
buf	Buffer to release
len	Length of the buffer (must be the exact same value as specified in `spdk_iobuf_get()`).

◆ spdk_iobuf_set_opts()

int spdk_iobuf_set_opts ( const struct spdk_iobuf_opts * opts )

Set iobuf options.

These options will be used during spdk_iobuf_initialize().

Parameters

opts	Options describing the size of the pools to reserve.

Returns: 0 on success, negative errno otherwise.

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

This function will also write NULL to the spdk_poller pointer pointed to by ppoller, to help encourage a poller pointer not getting reused after it has been unregistered.

It is OK to pass a ppoller parameter that points to NULL, in this case the function is a nop.

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_spin_destroy()

void spdk_spin_destroy ( struct spdk_spinlock * sspin )

Destroy an spdk_spinlock.

Parameters

sspin The SPDK spinlock to initialize.

◆ spdk_spin_held()

bool spdk_spin_held ( struct spdk_spinlock * sspin )

Determine if the caller holds this SPDK spinlock.

Parameters

sspin An SPDK spinlock.

Returns: true if spinlock is held by this thread, else false

◆ spdk_spin_init()

void spdk_spin_init ( struct spdk_spinlock * sspin )

Initialize an spdk_spinlock.

Parameters

sspin The SPDK spinlock to initialize.

◆ spdk_spin_lock()

void spdk_spin_lock ( struct spdk_spinlock * sspin )

Lock an SPDK spin lock.

Parameters

sspin An SPDK spinlock.

◆ spdk_spin_unlock()

void spdk_spin_unlock ( struct spdk_spinlock * sspin )

Unlock an SPDK spinlock.

Parameters

sspin An SPDK spinlock.

◆ spdk_thread_bind()

void spdk_thread_bind	(	struct spdk_thread *	thread,
		bool	bind )

Bind or unbind spdk_thread to its current CPU core.

If spdk_thread is bound, it couldn't be rescheduled to other CPU cores until it is unbound.

Parameters

thread	The thread to bind or not.
bind	true for bind, false for unbind.

◆ spdk_thread_create()

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

Creates a new SPDK thread object.

Note that the first thread created via spdk_thread_create() will be designated as the app thread. Other SPDK libraries may place restrictions on certain APIs to only be called in the context of this app thread.

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().

Note that this function must not be called on the app thread until after it has been called for all other threads.

Parameters

thread The thread to exit.

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

◆ spdk_thread_get_app_thread()

struct spdk_thread * spdk_thread_get_app_thread ( void )

Return the app thread.

The app thread is the first thread created using spdk_thread_create().

Returns: a pointer to the app thread, or NULL if no thread has been created yet.

◆ 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_interrupt_fd_group()

struct spdk_fd_group * spdk_thread_get_interrupt_fd_group ( struct spdk_thread * thread )

Return an fd_group that becomes ready whenever any of the registered interrupt file descriptors are ready.

Parameters

thread The thread to get.

Returns: The spdk_fd_group of the 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. If NULL, use current thread.

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_app_thread()

bool spdk_thread_is_app_thread ( struct spdk_thread * thread )

Check if the specified spdk_thread is the app thread.

Parameters

thread The thread to check. If NULL, check the current spdk_thread.

Returns: true if the specified spdk_thread is the app thread, false otherwise.

◆ spdk_thread_is_bound()

bool spdk_thread_is_bound ( struct spdk_thread * thread )

Returns whether the thread is bound to its current CPU core.

Parameters

thread The thread to query.

Returns: true if bound, false otherwise

◆ spdk_thread_is_exited()

bool spdk_thread_is_exited ( struct spdk_thread * thread )

Returns whether the thread is marked as exited.

A thread is exited only after it has spdk_thread_exit() called on it, and it has been polled until any outstanding operations targeting this thread have completed. This may include poller unregistrations, io channel unregistrations, or outstanding spdk_thread_send_msg calls.

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_is_running()

bool spdk_thread_is_running ( struct spdk_thread * thread )

Returns whether the thread is still running.

A thread is considered running until it has * spdk_thread_exit() called on it.

Parameters

thread The thread to query.

Returns: true if still running, 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 implementer 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

thread.h File Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Name of the module.

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_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_register_for_events()

◆ 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_iobuf_channel_fini()

◆ spdk_iobuf_channel_init()

◆ spdk_iobuf_entry_abort()

◆ spdk_iobuf_finish()

◆ spdk_iobuf_for_each_entry()

◆ spdk_iobuf_get()

◆ spdk_iobuf_get_opts()

◆ spdk_iobuf_get_stats()

◆ spdk_iobuf_initialize()

◆ spdk_iobuf_put()

◆ spdk_iobuf_set_opts()

◆ 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_spin_destroy()

◆ spdk_spin_held()

◆ spdk_spin_init()

◆ spdk_spin_lock()

◆ spdk_spin_unlock()

◆ spdk_thread_bind()

◆ spdk_thread_create()

◆ spdk_thread_destroy()

◆ spdk_thread_exec_msg()

◆ spdk_thread_exit()

◆ spdk_thread_get_app_thread()

◆ 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_interrupt_fd_group()

◆ spdk_thread_get_last_tsc()

◆ spdk_thread_get_name()