From 3e15e43b1fa979a53eab353fa95dc2ed10fcb17c Mon Sep 17 00:00:00 2001
From: "Evgeny Grin (Karlson2k)" <k2k@narod.ru>
Date: Sun, 23 Oct 2016 19:07:38 +0300
Subject: [PATCH] Added some remarks about functions' thread safety.

---
 src/microhttpd/connection.c | 6 ++++++
 src/microhttpd/connection.h | 4 ++++
 src/microhttpd/daemon.c     | 2 ++
 src/microhttpd/response.c   | 3 +++
 src/microhttpd/response.h   | 6 +++---
 5 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/microhttpd/connection.c b/src/microhttpd/connection.c
index e2271bba..bcc24705 100644
--- a/src/microhttpd/connection.c
+++ b/src/microhttpd/connection.c
@@ -492,6 +492,8 @@ need_100_continue (struct MHD_Connection *connection)
 /**
  * Close the given connection and give the
  * specified termination code to the user.
+ * @remark To be called only from thread that
+ * process connection's recv(), send() and response.
  *
  * @param connection connection to close
  * @param termination_code termination reason to give
@@ -2563,6 +2565,8 @@ MHD_connection_handle_write (struct MHD_Connection *connection)
 /**
  * Clean up the state of the given connection and move it into the
  * clean up queue for final disposal.
+ * @remark To be called only from thread that process connection's
+ * recv(), send() and response.
  *
  * @param connection handle for the connection to clean up
  */
@@ -2613,6 +2617,8 @@ cleanup_connection (struct MHD_Connection *connection)
 /**
  * This function was created to handle per-connection processing that
  * has to happen even if the socket cannot be read or written to.
+ * @remark To be called only from thread that process connection's
+ * recv(), send() and response.
  *
  * @param connection connection to handle
  * @return #MHD_YES if we should continue to process the
diff --git a/src/microhttpd/connection.h b/src/microhttpd/connection.h
index 4067af78..0fce7346 100644
--- a/src/microhttpd/connection.h
+++ b/src/microhttpd/connection.h
@@ -72,6 +72,8 @@ MHD_connection_handle_write (struct MHD_Connection *connection);
  * has to happen even if the socket cannot be read or written to.  All
  * implementations (multithreaded, external select, internal select)
  * call this function.
+ * @remark To be called only from thread that process connection's
+ * recv(), send() and response.
  *
  * @param connection connection to handle
  * @return MHD_YES if we should continue to process the
@@ -84,6 +86,8 @@ MHD_connection_handle_idle (struct MHD_Connection *connection);
 /**
  * Close the given connection and give the
  * specified termination code to the user.
+ * @remark To be called only from thread that
+ * process connection's recv(), send() and response.
  *
  * @param connection connection to close
  * @param termination_code termination reason to give
diff --git a/src/microhttpd/daemon.c b/src/microhttpd/daemon.c
index b7d0e0e7..916542f4 100644
--- a/src/microhttpd/daemon.c
+++ b/src/microhttpd/daemon.c
@@ -3683,6 +3683,8 @@ MHD_run (struct MHD_Daemon *daemon)
 /**
  * Close the given connection, remove it from all of its
  * DLLs and move it into the cleanup queue.
+ * @remark To be called only from thread that
+ * process daemon's select()/poll()/etc.
  *
  * @param pos connection to move to cleanup
  */
diff --git a/src/microhttpd/response.c b/src/microhttpd/response.c
index d0c72238..97b131cd 100644
--- a/src/microhttpd/response.c
+++ b/src/microhttpd/response.c
@@ -698,6 +698,9 @@ MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh,
  * We are done sending the header of a given response to the client.
  * Now it is time to perform the upgrade and hand over the connection
  * to the application.
+ * @remark To be called only from thread that process connection's
+ * recv(), send() and response. Must be called right after sending
+ * response headers.
  *
  * @param response the response that was created for an upgrade
  * @param connection the specific connection we are upgrading
diff --git a/src/microhttpd/response.h b/src/microhttpd/response.h
index ce7e131c..3f4717de 100644
--- a/src/microhttpd/response.h
+++ b/src/microhttpd/response.h
@@ -40,15 +40,15 @@ MHD_increment_response_rc (struct MHD_Response *response);
  * We are done sending the header of a given response
  * to the client.  Now it is time to perform the upgrade
  * and hand over the connection to the application.
+ * @remark To be called only from thread that process connection's
+ * recv(), send() and response. Must be called right after sending
+ * response headers.
  *
  * @param response the response that was created for an upgrade
  * @param connection the specific connection we are upgrading
  * @return #MHD_YES on success, #MHD_NO on failure (will cause
  *        connection to be closed)
  */
-// FIXME: This function will need to be called at the right place(s)
-// in the connection processing (just after we are done sending the header)
-// (for responses that have the 'upgrade_header' callback set).
 int
 MHD_response_execute_upgrade_ (struct MHD_Response *response,
                                struct MHD_Connection *connection);