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

TCP socket abstraction layer. More...

Data Structures

struct  spdk_sock_request
 Anywhere this struct is used, an iovec array is assumed to immediately follow the last member in memory, without any padding. More...
 
struct  spdk_sock_request::__sock_request_internal
 These fields are used by the socket layer and should not be modified. More...
 
struct  spdk_sock_impl_opts
 SPDK socket implementation options. More...
 
struct  spdk_sock_opts
 Spdk socket initialization options. More...
 

Macros

#define SPDK_SOCK_REQUEST_IOV(req, i)   ((struct iovec *)(((uint8_t *)req + sizeof(struct spdk_sock_request)) + (sizeof(struct iovec) * i)))
 
#define SPDK_TLS_VERSION_1_1   11
 
#define SPDK_TLS_VERSION_1_2   12
 
#define SPDK_TLS_VERSION_1_3   13
 
#define SPDK_SOCK_GROUP_REGISTER_INTERRUPT(sock, events, fn, arg)    spdk_sock_group_register_interrupt(sock, events, fn, arg, #fn)
 

Typedefs

typedef void(* spdk_sock_cb) (void *arg, struct spdk_sock_group *group, struct spdk_sock *sock)
 Callback function for spdk_sock_group_add_sock().
 

Enumerations

enum  spdk_placement_mode { PLACEMENT_NONE , PLACEMENT_NAPI , PLACEMENT_CPU , PLACEMENT_MARK }
 

Functions

 SPDK_STATIC_ASSERT (sizeof(struct spdk_sock_opts)==56, "Incorrect size")
 
void spdk_sock_get_default_opts (struct spdk_sock_opts *opts)
 Initialize the default value of opts.
 
int spdk_sock_getaddr (struct spdk_sock *sock, char *saddr, int slen, uint16_t *sport, char *caddr, int clen, uint16_t *cport)
 Get client and server addresses of the given socket.
 
const char * spdk_sock_get_impl_name (struct spdk_sock *sock)
 Get socket implementation name.
 
struct spdk_sock * spdk_sock_connect (const char *ip, int port, const char *impl_name)
 Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.
 
struct spdk_sock * spdk_sock_connect_ext (const char *ip, int port, const char *impl_name, struct spdk_sock_opts *opts)
 Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.
 
struct spdk_sock * spdk_sock_listen (const char *ip, int port, const char *impl_name)
 Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.
 
struct spdk_sock * spdk_sock_listen_ext (const char *ip, int port, const char *impl_name, struct spdk_sock_opts *opts)
 Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.
 
struct spdk_sock * spdk_sock_accept (struct spdk_sock *sock)
 Accept a new connection from a client on the specified socket and return a socket structure which holds the connection.
 
const char * spdk_sock_get_interface_name (struct spdk_sock *sock)
 Gets the name of the network interface of the local port for the socket.
 
int32_t spdk_sock_get_numa_id (struct spdk_sock *sock)
 Gets the NUMA node ID for the network interface of the local port for the TCP socket.
 
int spdk_sock_close (struct spdk_sock **sock)
 Close a socket.
 
int spdk_sock_flush (struct spdk_sock *sock)
 Flush a socket from data gathered in previous writev_async calls.
 
ssize_t spdk_sock_recv (struct spdk_sock *sock, void *buf, size_t len)
 Receive a message from the given socket.
 
ssize_t spdk_sock_writev (struct spdk_sock *sock, struct iovec *iov, int iovcnt)
 Write message to the given socket from the I/O vector array.
 
void spdk_sock_writev_async (struct spdk_sock *sock, struct spdk_sock_request *req)
 Write data to the given socket asynchronously, calling the provided callback when the data has been written.
 
ssize_t spdk_sock_readv (struct spdk_sock *sock, struct iovec *iov, int iovcnt)
 Read message from the given socket to the I/O vector array.
 
int spdk_sock_recv_next (struct spdk_sock *sock, void **buf, void **ctx)
 Receive the next portion of the stream from the socket.
 
int spdk_sock_set_recvlowat (struct spdk_sock *sock, int nbytes)
 Set the value used to specify the low water mark (in bytes) for this socket.
 
int spdk_sock_set_recvbuf (struct spdk_sock *sock, int sz)
 Set receive buffer size for the given socket.
 
int spdk_sock_set_sendbuf (struct spdk_sock *sock, int sz)
 Set send buffer size for the given socket.
 
bool spdk_sock_is_ipv6 (struct spdk_sock *sock)
 Check whether the address of socket is ipv6.
 
bool spdk_sock_is_ipv4 (struct spdk_sock *sock)
 Check whether the address of socket is ipv4.
 
bool spdk_sock_is_connected (struct spdk_sock *sock)
 Check whether the socket is currently connected.
 
struct spdk_sock_group * spdk_sock_group_create (void *ctx)
 Create a new socket group with user provided pointer.
 
void * spdk_sock_group_get_ctx (struct spdk_sock_group *sock_group)
 Get the ctx of the sock group.
 
int spdk_sock_group_add_sock (struct spdk_sock_group *group, struct spdk_sock *sock, spdk_sock_cb cb_fn, void *cb_arg)
 Add a socket to the group.
 
int spdk_sock_group_remove_sock (struct spdk_sock_group *group, struct spdk_sock *sock)
 Remove a socket from the group.
 
int spdk_sock_group_provide_buf (struct spdk_sock_group *group, void *buf, size_t len, void *ctx)
 Provides a buffer to the group to be used in its receive pool.
 
int spdk_sock_group_poll (struct spdk_sock_group *group)
 Poll incoming events for each registered socket.
 
int spdk_sock_group_poll_count (struct spdk_sock_group *group, int max_events)
 Poll incoming events up to max_events for each registered socket.
 
int spdk_sock_group_close (struct spdk_sock_group **group)
 Close all registered sockets of the group and then remove the group.
 
int spdk_sock_get_optimal_sock_group (struct spdk_sock *sock, struct spdk_sock_group **group, struct spdk_sock_group *hint)
 Get the optimal sock group for this sock.
 
int spdk_sock_impl_get_opts (const char *impl_name, struct spdk_sock_impl_opts *opts, size_t *len)
 Get current socket implementation options.
 
int spdk_sock_impl_set_opts (const char *impl_name, const struct spdk_sock_impl_opts *opts, size_t len)
 Set socket implementation options.
 
int spdk_sock_set_default_impl (const char *impl_name)
 Set the given sock implementation to be used as the default one.
 
const char * spdk_sock_get_default_impl (void)
 Get the name of the current default implementation.
 
void spdk_sock_write_config_json (struct spdk_json_write_ctx *w)
 Write socket subsystem configuration into provided JSON context.
 
int spdk_sock_group_register_interrupt (struct spdk_sock_group *group, uint32_t events, spdk_interrupt_fn fn, void *arg, const char *name)
 Register an spdk_interrupt with specific event types on the current thread for the given socket group.
 
void spdk_sock_group_unregister_interrupt (struct spdk_sock_group *group)
 Unregister an spdk_interrupt for the given socket group from the current thread.
 

Detailed Description

TCP socket abstraction layer.

Typedef Documentation

◆ spdk_sock_cb

typedef void(* spdk_sock_cb) (void *arg, struct spdk_sock_group *group, struct spdk_sock *sock)

Callback function for spdk_sock_group_add_sock().

Parameters
argArgument for the callback function.
groupSocket group.
sockSocket.

Function Documentation

◆ spdk_sock_accept()

struct spdk_sock * spdk_sock_accept ( struct spdk_sock * sock)

Accept a new connection from a client on the specified socket and return a socket structure which holds the connection.

Parameters
sockListening socket.
Returns
a pointer to the accepted socket on success, or NULL on failure.

◆ spdk_sock_close()

int spdk_sock_close ( struct spdk_sock ** sock)

Close a socket.

Parameters
sockSocket to close.
Returns
0 on success, -1 on failure.

◆ spdk_sock_connect()

struct spdk_sock * spdk_sock_connect ( const char * ip,
int port,
const char * impl_name )

Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

This function is used by client.

Parameters
ipIP address of the server.
portPort number of the server.
impl_nameThe sock_implementation to use, such as "posix". If impl_name is specified, it will only try to connect on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can connect.
Returns
a pointer to the connected socket on success, or NULL on failure.

◆ spdk_sock_connect_ext()

struct spdk_sock * spdk_sock_connect_ext ( const char * ip,
int port,
const char * impl_name,
struct spdk_sock_opts * opts )

Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

This function is used by client.

Parameters
ipIP address of the server.
portPort number of the server.
impl_nameThe sock_implementation to use, such as "posix". If impl_name is specified, it will only try to connect on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can connect.
optsThe sock option pointer provided by the user which should not be NULL pointer.
Returns
a pointer to the connected socket on success, or NULL on failure.

◆ spdk_sock_flush()

int spdk_sock_flush ( struct spdk_sock * sock)

Flush a socket from data gathered in previous writev_async calls.

Parameters
sockSocket to flush.
Returns
number of bytes sent on success, -1 (with errno set) on failure

◆ spdk_sock_get_default_impl()

const char * spdk_sock_get_default_impl ( void )

Get the name of the current default implementation.

Returns
The name of the default implementation

◆ spdk_sock_get_default_opts()

void spdk_sock_get_default_opts ( struct spdk_sock_opts * opts)

Initialize the default value of opts.

Parameters
optsData structure where SPDK will initialize the default sock options. Users must set opts_size to sizeof(struct spdk_sock_opts). This will ensure that the libraryonly tries to fill as many fields as allocated by the caller. This allows ABI compatibility with future versions of this library that may extend the spdk_sock_opts structure.

◆ spdk_sock_get_impl_name()

const char * spdk_sock_get_impl_name ( struct spdk_sock * sock)

Get socket implementation name.

Parameters
sockPointer to SPDK socket.
Returns
Implementation name of given socket.

◆ spdk_sock_get_interface_name()

const char * spdk_sock_get_interface_name ( struct spdk_sock * sock)

Gets the name of the network interface of the local port for the socket.

Parameters
socksocket to find the interface name for
Returns
null-terminated string containing interface name if found, NULL interface name could not be found

◆ spdk_sock_get_numa_id()

int32_t spdk_sock_get_numa_id ( struct spdk_sock * sock)

Gets the NUMA node ID for the network interface of the local port for the TCP socket.

Parameters
sockTCP socket to find the NUMA socket ID for
Returns
NUMA ID, or SPDK_ENV_NUMA_ID_ANY if the NUMA ID is unknown

◆ spdk_sock_get_optimal_sock_group()

int spdk_sock_get_optimal_sock_group ( struct spdk_sock * sock,
struct spdk_sock_group ** group,
struct spdk_sock_group * hint )

Get the optimal sock group for this sock.

Parameters
sockThe socket
groupReturns the optimal sock group. If there is no optimal sock group, returns NULL.
hintWhen return is 0 and group is set to NULL, hint is used to set optimal sock group for the socket.
Returns
0 on success. Negated errno on failure.

◆ spdk_sock_getaddr()

int spdk_sock_getaddr ( struct spdk_sock * sock,
char * saddr,
int slen,
uint16_t * sport,
char * caddr,
int clen,
uint16_t * cport )

Get client and server addresses of the given socket.

Parameters
sockSocket to get address.
saddrA pointer to the buffer to hold the address of server.
slenLength of the buffer 'saddr'.
sportA pointer(May be NULL) to the buffer to hold the port info of server.
caddrA pointer to the buffer to hold the address of client.
clenLength of the buffer 'caddr'.
cportA pointer(May be NULL) to the buffer to hold the port info of server.
Returns
0 on success, -1 on failure.

◆ spdk_sock_group_add_sock()

int spdk_sock_group_add_sock ( struct spdk_sock_group * group,
struct spdk_sock * sock,
spdk_sock_cb cb_fn,
void * cb_arg )

Add a socket to the group.

Parameters
groupSocket group.
sockSocket to add.
cb_fnCalled when the operation completes.
cb_argArgument passed to the callback function.
Returns
0 on success, -1 on failure with errno set.

◆ spdk_sock_group_close()

int spdk_sock_group_close ( struct spdk_sock_group ** group)

Close all registered sockets of the group and then remove the group.

Parameters
groupGroup to close.
Returns
0 on success, -1 on failure.

◆ spdk_sock_group_create()

struct spdk_sock_group * spdk_sock_group_create ( void * ctx)

Create a new socket group with user provided pointer.

Parameters
ctxthe context provided by user.
Returns
a pointer to the created group on success, or NULL on failure.

◆ spdk_sock_group_get_ctx()

void * spdk_sock_group_get_ctx ( struct spdk_sock_group * sock_group)

Get the ctx of the sock group.

Parameters
sock_groupSocket group.
Returns
a pointer which is ctx of the sock_group.

◆ spdk_sock_group_poll()

int spdk_sock_group_poll ( struct spdk_sock_group * group)

Poll incoming events for each registered socket.

Parameters
groupGroup to poll.
Returns
the number of events on success, -1 on failure.

◆ spdk_sock_group_poll_count()

int spdk_sock_group_poll_count ( struct spdk_sock_group * group,
int max_events )

Poll incoming events up to max_events for each registered socket.

Parameters
groupGroup to poll.
max_eventsNumber of maximum events to poll for each socket.
Returns
the number of events on success, -1 on failure.

◆ spdk_sock_group_provide_buf()

int spdk_sock_group_provide_buf ( struct spdk_sock_group * group,
void * buf,
size_t len,
void * ctx )

Provides a buffer to the group to be used in its receive pool.

See spdk_sock_recv_next() for more details.

Parameters
groupSocket group.
bufPointer the buffer provided.
lenLength of the buffer.
ctxPointer that will be returned in spdk_sock_recv_next()
Returns
0 on success, -1 on failure.

◆ spdk_sock_group_register_interrupt()

int spdk_sock_group_register_interrupt ( struct spdk_sock_group * group,
uint32_t events,
spdk_interrupt_fn fn,
void * arg,
const char * name )

Register an spdk_interrupt with specific event types on the current thread for the given socket group.

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
groupSocket group.
eventsEvent notification types.
fnCalled each time there are events in spdk_interrupt.
argFunction argument for fn.
nameHuman readable name for the spdk_interrupt.
Returns
0 on success or non-zero on failure.

◆ spdk_sock_group_remove_sock()

int spdk_sock_group_remove_sock ( struct spdk_sock_group * group,
struct spdk_sock * sock )

Remove a socket from the group.

Parameters
groupSocket group.
sockSocket to remove.
Returns
0 on success, -1 on failure with errno set.

◆ spdk_sock_group_unregister_interrupt()

void spdk_sock_group_unregister_interrupt ( struct spdk_sock_group * group)

Unregister an spdk_interrupt for the given socket group from the current thread.

Parameters
groupSocket group.

◆ spdk_sock_impl_get_opts()

int spdk_sock_impl_get_opts ( const char * impl_name,
struct spdk_sock_impl_opts * opts,
size_t * len )

Get current socket implementation options.

Parameters
impl_nameThe socket implementation to use, such as "posix".
optsPointer to allocated spdk_sock_impl_opts structure that will be filled with actual values.
lenOn input specifies size of passed opts structure. On return it is set to actual size that was filled with values.
Returns
0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_impl_set_opts()

int spdk_sock_impl_set_opts ( const char * impl_name,
const struct spdk_sock_impl_opts * opts,
size_t len )

Set socket implementation options.

Parameters
impl_nameThe socket implementation to use, such as "posix".
optsPointer to allocated spdk_sock_impl_opts structure with new options values.
lenSize of passed opts structure.
Returns
0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_is_connected()

bool spdk_sock_is_connected ( struct spdk_sock * sock)

Check whether the socket is currently connected.

Parameters
sockSocket to check
Returns
true if the socket is connected or false otherwise.

◆ spdk_sock_is_ipv4()

bool spdk_sock_is_ipv4 ( struct spdk_sock * sock)

Check whether the address of socket is ipv4.

Parameters
sockSocket to check.
Returns
true if the address of socket is ipv4, or false otherwise.

◆ spdk_sock_is_ipv6()

bool spdk_sock_is_ipv6 ( struct spdk_sock * sock)

Check whether the address of socket is ipv6.

Parameters
sockSocket to check.
Returns
true if the address of socket is ipv6, or false otherwise.

◆ spdk_sock_listen()

struct spdk_sock * spdk_sock_listen ( const char * ip,
int port,
const char * impl_name )

Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

This function is used by server.

Parameters
ipIP address to listen on.
portPort number.
impl_nameThe sock_implementation to use, such as "posix". If impl_name is specified, it will only try to listen on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can listen.
Returns
a pointer to the listened socket on success, or NULL on failure.

◆ spdk_sock_listen_ext()

struct spdk_sock * spdk_sock_listen_ext ( const char * ip,
int port,
const char * impl_name,
struct spdk_sock_opts * opts )

Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

This function is used by server.

Parameters
ipIP address to listen on.
portPort number.
impl_nameThe sock_implementation to use, such as "posix". If impl_name is specified, it will only try to listen on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can listen.
optsThe sock option pointer provided by the user, which should not be NULL pointer.
Returns
a pointer to the listened socket on success, or NULL on failure.

◆ spdk_sock_readv()

ssize_t spdk_sock_readv ( struct spdk_sock * sock,
struct iovec * iov,
int iovcnt )

Read message from the given socket to the I/O vector array.

Parameters
sockSocket to receive message.
iovI/O vector.
iovcntNumber of I/O vectors in the array.
Returns
the length of the received message on success, -1 on failure.

◆ spdk_sock_recv()

ssize_t spdk_sock_recv ( struct spdk_sock * sock,
void * buf,
size_t len )

Receive a message from the given socket.

Parameters
sockSocket to receive message.
bufPointer to a buffer to hold the data.
lenLength of the buffer.
Returns
the length of the received message on success, -1 on failure.

◆ spdk_sock_recv_next()

int spdk_sock_recv_next ( struct spdk_sock * sock,
void ** buf,
void ** ctx )

Receive the next portion of the stream from the socket.

A buffer provided to this socket's group's pool using spdk_sock_group_provide_buf() will contain the data and be returned in *buf.

Note that the amount of data in buf is determined entirely by the sock layer. You cannot request to receive only a limited amount here. You simply get whatever the next portion of the stream is, as determined by the sock module. You can place an upper limit on the size of the buffer since these buffers are originally provided to the group through spdk_sock_group_provide_buf().

This code path will only work if the recvbuf is disabled. To disable the recvbuf, call spdk_sock_set_recvbuf with a size of 0.

Parameters
sockSocket to receive from.
bufPopulated with the next portion of the stream
ctxReturned context pointer from when the buffer was provided.
Returns
On success, the length of the buffer placed into buf, On failure, -1 with errno set.

◆ spdk_sock_set_default_impl()

int spdk_sock_set_default_impl ( const char * impl_name)

Set the given sock implementation to be used as the default one.

Note: passing a specific sock implementation name in some sock API functions (such as spdk_sock_connect, spdk_sock_listen and etc) ignores the default value set by this function.

Parameters
impl_nameThe socket implementation to use, such as "posix".
Returns
0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_set_recvbuf()

int spdk_sock_set_recvbuf ( struct spdk_sock * sock,
int sz )

Set receive buffer size for the given socket.

Parameters
sockSocket to set buffer size for.
szBuffer size in bytes.
Returns
0 on success, -1 on failure.

◆ spdk_sock_set_recvlowat()

int spdk_sock_set_recvlowat ( struct spdk_sock * sock,
int nbytes )

Set the value used to specify the low water mark (in bytes) for this socket.

Parameters
sockSocket to set for.
nbytesValue for recvlowat.
Returns
0 on success, -1 on failure.

◆ spdk_sock_set_sendbuf()

int spdk_sock_set_sendbuf ( struct spdk_sock * sock,
int sz )

Set send buffer size for the given socket.

Parameters
sockSocket to set buffer size for.
szBuffer size in bytes.
Returns
0 on success, -1 on failure.

◆ spdk_sock_write_config_json()

void spdk_sock_write_config_json ( struct spdk_json_write_ctx * w)

Write socket subsystem configuration into provided JSON context.

Parameters
wJSON write context

◆ spdk_sock_writev()

ssize_t spdk_sock_writev ( struct spdk_sock * sock,
struct iovec * iov,
int iovcnt )

Write message to the given socket from the I/O vector array.

Parameters
sockSocket to write to.
iovI/O vector.
iovcntNumber of I/O vectors in the array.
Returns
the length of written message on success, -1 on failure.

◆ spdk_sock_writev_async()

void spdk_sock_writev_async ( struct spdk_sock * sock,
struct spdk_sock_request * req )

Write data to the given socket asynchronously, calling the provided callback when the data has been written.

Parameters
sockSocket to write to.
reqThe write request to submit.