locking: Simplify maintenance / debugging /documentation

Update libcoap functions that need to be called locked with a name
suffix of _locked.

Move matching functions out of coap_threadsafe.c to be coded just ahead
of the newly renamed _locked function.

Properly define the _locked function in the appropriate _internal.h file
for documentation, removing the #defines from coap_threadsafe_internal.h.

Work in progress for all the functions.

Remove coap_lock_* requirements for testdriver (coap_delete_node()).

include/coap3/coap_net.h

@@ -696,15 +696,6 @@ int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
  */
 int coap_io_pending(coap_context_t *context);
 
-/**@}*/
-
-/**
- * @ingroup internal_api
- * @defgroup app_io_internal Application I/O Handling
- * Internal API for Application Input / Output checking
- * @{
- */
-
 /**
 * Iterates through all the coap_socket_t structures embedded in endpoints or
 * sessions associated with the @p ctx to determine which are wanting any
@@ -894,8 +885,7 @@ coap_write(coap_context_t *ctx,
            coap_socket_t *sockets[],
            unsigned int max_sockets,
            unsigned int *num_sockets,
-           coap_tick_t now
-          ) {
+           coap_tick_t now) {
   return coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now);
 }
 
@@ -910,8 +900,7 @@ coap_write(coap_context_t *ctx,
  * @param now Current time
  */
 COAP_STATIC_INLINE COAP_DEPRECATED void
-coap_read(coap_context_t *ctx, coap_tick_t now
-         ) {
+coap_read(coap_context_t *ctx, coap_tick_t now) {
   coap_io_do_io(ctx, now);
 }
 

include/coap3/coap_net_internal.h

@@ -221,6 +221,17 @@ int coap_insert_node(coap_queue_t **queue, coap_queue_t *node);
  */
 int coap_delete_node(coap_queue_t *node);
 
+/**
+ * Destroys specified @p node.
+ *
+ * Note: Needs to be called in a locked state if node->session is set.
+ *
+ * @param node Node entry to remove.
+ *
+ * @return @c 1 node deleted from queue, @c 0 failure.
+ */
+int coap_delete_node_locked(coap_queue_t *node);
+
 /**
  * Removes all items from given @p queue and frees the allocated storage.
  *
@@ -435,8 +446,204 @@ coap_mid_t coap_send_internal(coap_session_t *session, coap_pdu_t *pdu);
  */
 int coap_client_delay_first(coap_session_t *session);
 
+/**
+ * CoAP stack context must be released with coap_free_context_locked(). This
+ * function  clears all entries from the receive queue and send queue and deletes the
+ * resources that have been registered with @p context, and frees the attached
+ * endpoints.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param context The current coap_context_t object to free off.
+ */
+void coap_free_context_locked(coap_context_t *context);
+
 /** @} */
 
+/**
+ * @ingroup internal_api
+ * @defgroup app_io_internal Application I/O Handling
+ * Internal API for Application Input / Output checking
+ * @{
+ */
+
+/**
+ * Processes any outstanding read, write, accept or connect I/O as indicated
+ * in the coap_socket_t structures (COAP_SOCKET_CAN_xxx set) embedded in
+ * endpoints or sessions associated with @p ctx.
+ *
+ * Note: If epoll support is compiled into libcoap, coap_io_do_epoll_locked() must
+ * be used instead of coap_io_do_io_locked().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context
+ * @param now Current time
+ */
+void coap_io_do_io_locked(coap_context_t *ctx, coap_tick_t now);
+
+/**
+ * Process all the epoll events
+ *
+ * Note: If epoll support is compiled into libcoap, coap_io_do_epoll_locked() must
+ * be used instead of coap_io_do_io_locked().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx    The current CoAP context.
+ * @param events The list of events returned from an epoll_wait() call.
+ * @param nevents The number of events.
+ *
+ */
+void coap_io_do_epoll_locked(coap_context_t *ctx, struct epoll_event *events,
+                             size_t nevents);
+
+/**
+ * Check to see if there is any i/o pending for the @p context.
+ *
+ * This includes Observe active (client) and partial large block transfers.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * coap_io_process() is called internally to try to send outstanding
+ * data as well as process any packets just received.
+ *
+ * @param context The CoAP context.
+ *
+ * @return @c 1 I/O still pending, @c 0 no I/O pending.
+ */
+int coap_io_pending_locked(coap_context_t *context);
+
+/**
+ * Any now timed out delayed packet is transmitted, along with any packets
+ * associated with requested observable response.
+ *
+ * In addition, it returns when the next expected I/O is expected to take place
+ * (e.g. a packet retransmit).
+ *
+ * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll_locked()
+ * must  be used instead of coap_io_prepare_io_locked().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context
+ * @param now Current time.
+ *
+ * @return timeout Maxmimum number of milliseconds that can be used by a
+ *                 epoll_wait() to wait for network events or 0 if wait should be
+ *                 forever.
+ */
+unsigned int coap_io_prepare_epoll_locked(coap_context_t *ctx, coap_tick_t now);
+
+/**
+ * Iterates through all the coap_socket_t structures embedded in endpoints or
+ * sessions associated with the @p ctx to determine which are wanting any
+ * read, write, accept or connect I/O (COAP_SOCKET_WANT_xxx is set). If set,
+ * the coap_socket_t is added to the @p sockets.
+ *
+ * Any now timed out delayed packet is transmitted, along with any packets
+ * associated with requested observable response.
+ *
+ * In addition, it returns when the next expected I/O is expected to take place
+ * (e.g. a packet retransmit).
+ *
+ * Prior to calling coap_io_do_io_locked(), the @p sockets must be tested to see
+ * if any of the COAP_SOCKET_WANT_xxx have the appropriate information and if
+ * so, COAP_SOCKET_CAN_xxx is set. This typically will be done after using a
+ * select() call.
+ *
+ * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll_locked()
+ * must be used instead of coap_io_prepare_io_locked().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context
+ * @param sockets Array of socket descriptors, filled on output
+ * @param max_sockets Size of socket array.
+ * @param num_sockets Pointer to the number of valid entries in the socket
+ *                    arrays on output.
+ * @param now Current time.
+ *
+ * @return timeout Maxmimum number of milliseconds that can be used by a
+ *                 select() to wait for network events or 0 if wait should be
+ *                 forever.
+ */
+unsigned int coap_io_prepare_io_locked(coap_context_t *ctx,
+                                       coap_socket_t *sockets[],
+                                       unsigned int max_sockets,
+                                       unsigned int *num_sockets,
+                                       coap_tick_t now
+                                      );
+
+/**
+ * The main I/O processing function.  All pending network I/O is completed,
+ * and then optionally waits for the next input packet.
+ *
+ * This internally calls coap_io_prepare_io(), then select() for the appropriate
+ * sockets, updates COAP_SOCKET_CAN_xxx where appropriate and then calls
+ * coap_io_do_io() before returning with the time spent in the function.
+ *
+ * Alternatively, if libcoap is compiled with epoll support, this internally
+ * calls coap_io_prepare_epoll(), then epoll_wait() for waiting for any file
+ * descriptors that have (internally) been set up with epoll_ctl() and
+ * finally coap_io_do_epoll() before returning with the time spent in the
+ * function.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context
+ * @param timeout_ms Minimum number of milliseconds to wait for new packets
+ *                   before returning after doing any processing.
+ *                   If COAP_IO_WAIT, the call will block until the next
+ *                   internal action (e.g. packet retransmit) if any, or block
+ *                   until the next packet is received whichever is the sooner
+ *                   and do the necessary processing.
+ *                   If COAP_IO_NO_WAIT, the function will return immediately
+ *                   after processing without waiting for any new input
+ *                   packets to arrive.
+ *
+ * @return Number of milliseconds spent in function or @c -1 if there was
+ *         an error
+ */
+int coap_io_process_locked(coap_context_t *ctx, uint32_t timeout_ms);
+
+#if !defined(RIOT_VERSION) && !defined(WITH_CONTIKI)
+/**
+ * The main message processing loop with additional fds for internal select.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context
+ * @param timeout_ms Minimum number of milliseconds to wait for new packets
+ *                   before returning after doing any processing.
+ *                   If COAP_IO_WAIT, the call will block until the next
+ *                   internal action (e.g. packet retransmit) if any, or block
+ *                   until the next packet is received whichever is the sooner
+ *                   and do the necessary processing.
+ *                   If COAP_IO_NO_WAIT, the function will return immediately
+ *                   after processing without waiting for any new input
+ *                   packets to arrive.
+ * @param nfds      The maximum FD set in readfds, writefds or exceptfds
+ *                  plus one,
+ * @param readfds   Read FDs to additionally check for in internal select()
+ *                  or NULL if not required.
+ * @param writefds  Write FDs to additionally check for in internal select()
+ *                  or NULL if not required.
+ * @param exceptfds Except FDs to additionally check for in internal select()
+ *                  or NULL if not required.
+ *
+ *
+ * @return Number of milliseconds spent in coap_io_process_with_fds, or @c -1
+ *         if there was an error.  If defined, readfds, writefds, exceptfds
+ *         are updated as returned by the internal select() call.
+ */
+int coap_io_process_with_fds_locked(coap_context_t *ctx, uint32_t timeout_ms,
+                                    int nfds, fd_set *readfds, fd_set *writefds,
+                                    fd_set *exceptfds);
+#endif /* ! RIOT_VERSION && ! WITH_CONTIKI */
+
+/**@}*/
+
 extern int coap_started;
 
 #endif /* COAP_NET_INTERNAL_H_ */

include/coap3/coap_threadsafe_internal.h

@@ -43,18 +43,8 @@
 #define coap_find_async(s,t)                            coap_find_async_locked(s,t)
 #define coap_delete_oscore_recipient(s,r)               coap_delete_oscore_recipient_locked(s,r)
 #define coap_delete_resource(c,r)                       coap_delete_resource_locked(c,r)
-#define coap_free_context(c)                            coap_free_context_locked(c)
 #define coap_free_endpoint(e)                           coap_free_endpoint_locked(e)
 #define coap_get_resource_from_uri_path(c,u)            coap_get_resource_from_uri_path_locked(c,u)
-#define coap_io_do_epoll(c,e,n)                         coap_io_do_epoll_locked(c,e,n)
-#define coap_io_do_io(c,n)                              coap_io_do_io_locked(c,n)
-#define coap_io_pending(c)                              coap_io_pending_locked(c)
-#define coap_io_prepare_epoll(c,n)                      coap_io_prepare_epoll_locked(c,n)
-#define coap_io_prepare_io(c,s,m,n,t)                   coap_io_prepare_io_locked(c,s,m,n,t)
-#define coap_io_process(s,t)                            coap_io_process_locked(s,t)
-#ifdef HAVE_SYS_SELECT_H
-#define coap_io_process_with_fds(s,t,n,r,w,e)           coap_io_process_with_fds_locked(s,t,n,r,w,e)
-#endif /* HAVE_SYS_SELECT_H */
 #define coap_join_mcast_group_intf(c,g,i)               coap_join_mcast_group_intf_locked(c,g,i)
 #define coap_new_cache_entry(s,p,r,b,i)                 coap_new_cache_entry_locked(s,p,r,b,i)
 #define coap_new_client_session(c,l,s,p)                coap_new_client_session_locked(c,l,s,p)
@@ -142,20 +132,9 @@ int                  coap_delete_oscore_recipient_locked(coap_context_t *context
                                                          coap_bin_const_t *recipient_id);
 int                  coap_delete_resource_locked(coap_context_t *context, coap_resource_t *resource);
 coap_async_t        *coap_find_async_locked(coap_session_t *session, coap_bin_const_t token);
-void                 coap_free_context_locked(coap_context_t *context);
 void                 coap_free_endpoint_locked(coap_endpoint_t *ep);
 coap_resource_t     *coap_get_resource_from_uri_path_locked(coap_context_t *context,
                                                             coap_str_const_t *uri_path);
-void                 coap_io_do_epoll_locked(coap_context_t *ctx, struct epoll_event *events,
-                                             size_t nevents);
-void                 coap_io_do_io_locked(coap_context_t *ctx, coap_tick_t now);
-int                  coap_io_pending_locked(coap_context_t *context);
-unsigned int         coap_io_prepare_epoll_locked(coap_context_t *ctx, coap_tick_t now);
-unsigned int         coap_io_prepare_io_locked(coap_context_t *ctx,
-                                               coap_socket_t *sockets[],
-                                               unsigned int max_sockets,
-                                               unsigned int *num_sockets,
-                                               coap_tick_t now);
 int                  coap_join_mcast_group_intf_locked(coap_context_t *ctx, const char *group_name,
                                                        const char *ifname);
 coap_subscription_t *coap_persist_observe_add_locked(coap_context_t *context,
@@ -170,12 +149,6 @@ int                  coap_persist_startup_locked(coap_context_t *context,
                                                  const char *obs_cnt_save_file,
                                                  uint32_t save_freq);
 void                 coap_persist_stop_locked(coap_context_t *context);
-int                  coap_io_process_locked(coap_context_t *ctx, uint32_t timeout_ms);
-#ifdef HAVE_SYS_SELECT_H
-int                  coap_io_process_with_fds_locked(coap_context_t *ctx, uint32_t timeout_ms,
-                                                     int nfds, fd_set *readfds, fd_set *writefds,
-                                                     fd_set *exceptfds);
-#endif /* HAVE_SYS_SELECT_H */
 coap_async_t        *coap_register_async_locked(coap_session_t *session, const coap_pdu_t *request,
                                                 coap_tick_t delay);
 size_t               coap_session_max_pdu_size_locked(const coap_session_t *session);