Loading...
Searching...
No Matches
thread.h File Reference

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_cache
 
struct  spdk_iobuf_node_cache
 
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)
 
#define SPDK_INTERRUPT_REGISTER_EXT(efd, fn, arg, opts)    spdk_interrupt_register_ext(efd, fn, arg, #fn, opts)
 
#define SPDK_CONFIG_MAX_NUMA_NODES   1
 

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_cpusetspdk_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.
 
uint16_t spdk_thread_get_trace_id (struct spdk_thread *thread)
 Get trace id.
 
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.
 
struct spdk_interrupt * spdk_interrupt_register_ext (int efd, spdk_interrupt_fn fn, void *arg, const char *name, struct spdk_event_handler_opts *opts)
 Register an spdk_interrupt with specific event type stated in spdk_event_handler_opts argument on the current thread.
 
struct spdk_interrupt * spdk_interrupt_register_fd_group (struct spdk_fd_group *fgrp, const char *name)
 Register an interrupt listening for all events associated with an fd_group on 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)
 
typedef void(* spdk_post_poller_fn) (void *fn_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, spdk_iobuf_for_each_entry_fn cb_fn, void *cb_ctx)
 Iterate over all entries on a given channel and execute a callback on those that were requested.
 
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.
 
void spdk_thread_register_post_poller_handler (spdk_post_poller_fn fn, void *fn_arg)
 Register a function to be called after the current SPDK poller has completed.
 

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
iI/O channel iterator.
status0 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
iI/O channel iterator.

◆ spdk_interrupt_fn

typedef int(* spdk_interrupt_fn) (void *ctx)

Callback function registered for interrupt file descriptor.

Parameters
ctxContext 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_deviceI/O device associated with this channel.
ctx_bufContext 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_deviceI/O device associated with this channel.
ctx_bufContext 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_deviceUnregistered I/O device.

◆ spdk_msg_fn

typedef void(* spdk_msg_fn) (void *ctx)

A function that will be called on the target thread.

Parameters
ctxContext 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
threadThe new spdk_thread.

◆ spdk_poller_fn

typedef int(* spdk_poller_fn) (void *ctx)

Callback function for a poller.

Parameters
ctxContext 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
pollerPoller to set interrupt or poll mode.
cb_argArgument passed to the callback function.
interrupt_modeSet 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
fnCallback function for a thread.
ctxContext passed to fn.
thread_ctxContext 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.
fnCalled on the appropriate thread for each channel associated with io_device.
ctxContext buffer registered to spdk_io_channel_iter that can be obtained form the function spdk_io_channel_iter_get_ctx().
cplCalled 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
iI/O channel iterator.
statusStatus 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
fnThis is the function that will be called on each thread.
ctxThis context will be passed to fn when called.
cplThis 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_deviceThe 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
efdFile descriptor of the spdk_interrupt.
fnCalled each time there are events in spdk_interrupt.
argFunction argument for fn.
nameHuman 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_ext()

struct spdk_interrupt * spdk_interrupt_register_ext ( int efd,
spdk_interrupt_fn fn,
void * arg,
const char * name,
struct spdk_event_handler_opts * opts )

Register an spdk_interrupt with specific event type stated in spdk_event_handler_opts argument on the current thread.

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

Parameters
efdFile descriptor of the spdk_interrupt.
fnCalled each time there are events in spdk_interrupt.
argFunction argument for fn.
nameHuman readable name for the spdk_interrupt. Pointer of the spdk_interrupt name is set if NULL.
optsExtended event handler option.
Returns
a pointer to the spdk_interrupt registered on the current thread on success or NULL on failure.

◆ spdk_interrupt_register_fd_group()

struct spdk_interrupt * spdk_interrupt_register_fd_group ( struct spdk_fd_group * fgrp,
const char * name )

Register an interrupt listening for all events associated with an fd_group on current thread.

Parameters
fgrpfd_group describing the events to listen for.
nameName of the interrupt.

return Pointer to spdk_interrupt or NULL in case of 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
efdFile descriptor of the spdk_interrupt.
eventsEvent notification types.
fnCalled each time there are events in spdk_interrupt.
argFunction argument for fn.
nameHuman 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
intrThe pointer to the spdk_interrupt registered on the current thread.
event_typesNew 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
pintrThe 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
ctxThe 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
chI/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
chI/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
chI/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
iI/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
iI/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
iI/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_deviceThe pointer to io_device context.
create_cbCallback function invoked to allocate any resources required for a new I/O channel.
destroy_cbCallback function invoked to release the resources for an I/O channel.
ctx_sizeThe size of the context buffer allocated to store references to allocated I/O channel resources.
nameA 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_deviceThe pointer to io_device context.
unregister_cbAn 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
chiobuf 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
chiobuf channel to initialize.
nameName of the module registered via spdk_iobuf_register_module().
small_cache_sizeNumber of small buffers to be cached by this channel.
large_cache_sizeNumber 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
chiobuf channel on which the entry is waiting.
entryEntry to remove from the wait queue.
lenLength 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_fnCallback to be executed once the clean up is completed.
cb_argCallback argument.

◆ spdk_iobuf_for_each_entry()

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

Iterate over all entries on a given channel and execute a callback on those that were requested.

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

Parameters
chiobuf channel to iterate over.
cb_fnCallback to execute on each entry on the channel that was requested.
cb_ctxArgument 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
chiobuf channel.
lenLength of the buffer to retrieve. The user is responsible for making sure the length doesn't exceed large_bufsize.
entryWait queue entry (optional).
cb_fnCallback 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
optsOutput parameter for options.
opts_sizesizeof(*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_fnCallback to be executed once stats are gathered.
cb_argArgument 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
chiobuf channel.
bufBuffer to release
lenLength 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
optsOptions 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
pollerThe 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
fnThis function will be called every period_microseconds.
argArgument passed to fn.
period_microsecondsHow 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.

Callers may pass NULL for the cb_fn, signifying that no callback is necessary when the interrupt mode changes.

Parameters
pollerThe poller to register callback function.
cb_fnCallback function called when the poller must transition into or out of interrupt mode
cb_argArgument 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
fnThis function will be called every period_microseconds.
argArgument passed to fn.
period_microsecondsHow often to call fn. If 0, call fn as often as possible.
nameHuman 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
pollerThe 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
ppollerThe 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
chI/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
threadThe thread to set.

◆ spdk_spin_destroy()

void spdk_spin_destroy ( struct spdk_spinlock * sspin)

Destroy an spdk_spinlock.

Parameters
sspinThe SPDK spinlock to initialize.

◆ spdk_spin_held()

bool spdk_spin_held ( struct spdk_spinlock * sspin)

Determine if the caller holds this SPDK spinlock.

Parameters
sspinAn 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
sspinThe SPDK spinlock to initialize.

◆ spdk_spin_lock()

void spdk_spin_lock ( struct spdk_spinlock * sspin)

Lock an SPDK spin lock.

Parameters
sspinAn SPDK spinlock.

◆ spdk_spin_unlock()

void spdk_spin_unlock ( struct spdk_spinlock * sspin)

Unlock an SPDK spinlock.

Parameters
sspinAn 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
threadThe thread to bind or not.
bindtrue 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
nameHuman-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.
cpumaskOptional 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
threadThe 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
threadThe target thread.
fnThis function will be called on the given thread.
ctxThis 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
threadThe 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
idID 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
threadThe 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
threadThe 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
ctxA 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
threadThread 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
threadThe 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
threadThe 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
threadThread 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
threadThread 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
statsUser's thread_stats structure.

◆ spdk_thread_get_trace_id()

uint16_t spdk_thread_get_trace_id ( struct spdk_thread * thread)

Get trace id.

Parameters
threadThread to get trace_id from.
Returns
Trace id of the specified thread.

◆ 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
threadThe 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
threadThe 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
threadThe 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
threadThe 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
threadThe 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
threadThe 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
threadThe 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_fnCalled each time a new SPDK thread is created. The implementer is expected to frequently call spdk_thread_poll() on the provided thread.
ctx_szFor 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_fnCalled for SPDK thread operation.
thread_op_supported_fnCalled to check whether the SPDK thread operation is supported.
ctx_szFor 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_sizeSize 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
threadThe 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
threadThe thread to process
max_msgsThe maximum number of messages that will be processed. Use 0 to process the default number of messages (8).
nowThe 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_register_post_poller_handler()

void spdk_thread_register_post_poller_handler ( spdk_post_poller_fn fn,
void * fn_arg )

Register a function to be called after the current SPDK poller has completed.

Once called, this function is de-registered and won't called until the next registration call.

Parameters
fnFunction to call
fn_argFunction argument

◆ 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
threadThe target thread.
fnThis 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
threadThe target thread.
fnThis function will be called on the given thread.
ctxThis 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
cpumaskThe 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_interruptSet interrupt mode for true, or poll mode for false