Commit 173be047 authored by Jacek Kalwas's avatar Jacek Kalwas Committed by Tomasz Zawadzki
Browse files

sock: add deprecation for spdk_sock_* return behavior 



This change aims to align return behavior of sock functions to majority
of SPDK public functions. Moreover, it aligns behavior within sock
itself as `spdk_sock_request.cb_fn` or
`spdk_sock_get_optimal_sock_group` already return negative errno value
on failure. The same cleanup is planned for util/net which is used by
sock modules.

Change-Id: I8c728d7a8542e2c79bea9aac078c4a37333efcf7
Signed-off-by: default avatarJacek Kalwas <jacek.kalwas@nutanix.com>
Reviewed-on: https://review.spdk.io/c/spdk/spdk/+/26051


Tested-by: default avatarSPDK Automated Test System <spdkbot@gmail.com>
Reviewed-by: default avatarJim Harris <jim.harris@nvidia.com>
Reviewed-by: default avatarTomasz Zawadzki <tomasz@tzawadzki.com>
parent 06668d50

deprecation.md

+12 −0
Original line number Diff line number Diff line
@@ -21,6 +21,18 @@ The tags can be matched with the level 4 headers below. 


### sock



#### `spdk_sock_\*`



`spdk_sock_getaddr`, `spdk_sock_close`, `spdk_sock_flush`, `spdk_sock_recv`, `spdk_sock_writev`,

`spdk_sock_readv`, `spdk_sock_recv_next`, `spdk_sock_set_recvlowat`, `spdk_sock_set_recvbuf`,

`spdk_sock_set_sendbuf`, `spdk_sock_group_add_sock`, `spdk_sock_group_remove_sock`,

`spdk_sock_group_provide_buf`, `spdk_sock_group_poll`, `spdk_sock_group_poll_count`,

`spdk_sock_group_close`, `spdk_sock_impl_get_opts`, `spdk_sock_impl_set_opts`,

`spdk_sock_set_default_impl`, `spdk_sock_group_register_interrupt`



Returning -1 and setting errno on these functions is deprecated and will be changed in the 26.01

release. These functions will return negative errno values instead.



#### `spdk_sock_flush`



This function returnes number of bytes sent on success, whereas this behavior is deprecated and

include/spdk/sock.h

+53 −0
Original line number Diff line number Diff line
@@ -275,6 +275,9 @@ void spdk_sock_get_default_opts(struct spdk_sock_opts *opts); 
/**

 * Get client and server addresses of the given socket.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to get address.

 * \param saddr A pointer to the buffer to hold the address of server.

 * \param slen Length of the buffer 'saddr'.
@@ -398,6 +401,9 @@ int32_t spdk_sock_get_numa_id(struct spdk_sock *sock); 
/**

 * Close a socket.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to close.

 *

 * \return 0 on success, -1 on failure.
@@ -412,6 +418,8 @@ int spdk_sock_close(struct spdk_sock **sock); 
 * It is not recommended to rely on the number of bytes returned on success.

 * This behavior is deprecated and will be removed in 25.09 release, function

 * will return 0 on success instead.

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to flush.

 *
@@ -424,6 +432,9 @@ int spdk_sock_flush(struct spdk_sock *sock); 
 *

 * On failure check errno matching EAGAIN to determine failure is retryable.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to receive message.

 * \param buf Pointer to a buffer to hold the data.

 * \param len Length of the buffer.
@@ -437,6 +448,9 @@ ssize_t spdk_sock_recv(struct spdk_sock *sock, void *buf, size_t len); 
 *

 * On failure check errno matching EAGAIN to determine failure is retryable.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to write to.

 * \param iov I/O vector.

 * \param iovcnt Number of I/O vectors in the array.
@@ -457,6 +471,9 @@ void spdk_sock_writev_async(struct spdk_sock *sock, struct spdk_sock_request *re 
/**

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

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to receive message.

 * \param iov I/O vector.

 * \param iovcnt Number of I/O vectors in the array.
@@ -484,6 +501,9 @@ ssize_t spdk_sock_readv(struct spdk_sock *sock, struct iovec *iov, int iovcnt); 
 *

 * On failure check errno matching EAGAIN to determine failure is retryable.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to receive from.

 * \param buf Populated with the next portion of the stream

 * \param ctx Returned context pointer from when the buffer was provided.
@@ -495,6 +515,9 @@ int spdk_sock_recv_next(struct spdk_sock *sock, void **buf, void **ctx); 
/**

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

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to set for.

 * \param nbytes Value for recvlowat.

 *
@@ -505,6 +528,9 @@ int spdk_sock_set_recvlowat(struct spdk_sock *sock, int nbytes); 
/**

 * Set receive buffer size for the given socket.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to set buffer size for.

 * \param sz Buffer size in bytes.

 *
@@ -515,6 +541,9 @@ int spdk_sock_set_recvbuf(struct spdk_sock *sock, int sz); 
/**

 * Set send buffer size for the given socket.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock Socket to set buffer size for.

 * \param sz Buffer size in bytes.

 *
@@ -578,6 +607,9 @@ void *spdk_sock_group_get_ctx(struct spdk_sock_group *sock_group); 
/**

 * Add a socket to the group.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param group Socket group.

 * \param sock Socket to add.

 * \param cb_fn Called when the operation completes.
@@ -602,6 +634,9 @@ int spdk_sock_group_remove_sock(struct spdk_sock_group *group, struct spdk_sock 
 * Provides a buffer to the group to be used in its receive pool.

 * See spdk_sock_recv_next() for more details.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param group Socket group.

 * \param buf Pointer the buffer provided.

 * \param len Length of the buffer.
@@ -623,6 +658,9 @@ int spdk_sock_group_poll(struct spdk_sock_group *group); 
/**

 * Poll incoming events up to max_events for each registered socket.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param group Group to poll.

 * \param max_events Number of maximum events to poll for each socket.

 *
@@ -633,6 +671,9 @@ int spdk_sock_group_poll_count(struct spdk_sock_group *group, int max_events); 
/**

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

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * If any sockets were added to the group by \ref spdk_sock_group_add_sock

 * these must be removed first by using \ref spdk_sock_group_remove_sock.

 *
@@ -645,6 +686,9 @@ int spdk_sock_group_close(struct spdk_sock_group **group); 
/**

 * Get the optimal sock group for this sock.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param sock The socket

 * \param group Returns the optimal sock group. If there is no optimal sock group, returns NULL.

 * \param hint When return is 0 and group is set to NULL, hint is used to set optimal sock group for the socket.
@@ -657,6 +701,9 @@ int spdk_sock_get_optimal_sock_group(struct spdk_sock *sock, struct spdk_sock_gr 
/**

 * Get current socket implementation options.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param impl_name The socket implementation to use, such as "posix".

 * \param opts Pointer to allocated spdk_sock_impl_opts structure that will be filled with actual values.

 * \param len On input specifies size of passed opts structure. On return it is set to actual size that was filled with values.
@@ -668,6 +715,9 @@ int spdk_sock_impl_get_opts(const char *impl_name, struct spdk_sock_impl_opts *o 
/**

 * Set socket implementation options.

 *

 * Returning -1 and setting errno is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * \param impl_name The socket implementation to use, such as "posix".

 * \param opts Pointer to allocated spdk_sock_impl_opts structure with new options values.

 * \param len Size of passed opts structure.
@@ -705,6 +755,9 @@ void spdk_sock_write_config_json(struct spdk_json_write_ctx *w); 
/**

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

 *

 * Returning non-zero is deprecated and will be changed in the 26.01 release.

 * This function will return negative errno values instead.

 *

 * 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