From b02b16ab98330f3471919a57ec0d4e087e2fa924 Mon Sep 17 00:00:00 2001
From: Alexander Tkachev
Date: Thu, 2 Jun 2016 11:37:10 +0600
Subject: CLOUD: Document ConnectionManager's onDeleteCallback

---
 backends/networking/curl/connectionmanager.cpp |  4 ++--
 backends/networking/curl/connectionmanager.h   | 28 +++++++++++++++++++++++---
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/backends/networking/curl/connectionmanager.cpp b/backends/networking/curl/connectionmanager.cpp
index a3cad0d005..44511fdb23 100644
--- a/backends/networking/curl/connectionmanager.cpp
+++ b/backends/networking/curl/connectionmanager.cpp
@@ -47,7 +47,7 @@ ConnectionManager::~ConnectionManager() {
 	_handleMutex.lock();
 	for (Common::Array<RequestWithCallback>::iterator i = _requests.begin(); i != _requests.end(); ++i) {
 		Request *request = i->request;
-		RequestCallback callback = i->callback;
+		RequestCallback callback = i->onDeleteCallback;
 		if (request) request->finish();
 		delete request;
 		if (callback) (*callback)(request);
@@ -107,7 +107,7 @@ void ConnectionManager::interateRequests() {
 		Request *request = i->request;
 		if (!request || request->state() == FINISHED) {
 			delete (i->request);
-			if (i->callback) (*i->callback)(i->request); //that's not a mistake (we're passing an address and that method knows there is no object anymore)
+			if (i->onDeleteCallback) (*i->onDeleteCallback)(i->request); //that's not a mistake (we're passing an address and that method knows there is no object anymore)
 			_requests.erase(i);
 			continue;
 		}
diff --git a/backends/networking/curl/connectionmanager.h b/backends/networking/curl/connectionmanager.h
index 75cff0587b..a91bc01d87 100644
--- a/backends/networking/curl/connectionmanager.h
+++ b/backends/networking/curl/connectionmanager.h
@@ -42,11 +42,31 @@ class ConnectionManager : public Common::Singleton<ConnectionManager> {
 
 	typedef Common::BaseCallback<Request *> *RequestCallback;
 
-	struct RequestWithCallback { //I'm completely out of ideas
+	/**
+	 * RequestWithCallback is used by ConnectionManager to
+	 * storage the Request and a callback which should be
+	 * called on Request delete.
+	 *
+	 * Usually one won't need to pass such callback, but
+	 * in some cases you'd like to know whether Request is
+	 * still running.
+	 *
+	 * For example, Cloud::Storage is keeping track of how
+	 * many Requests are running, and thus it needs to know
+	 * that Request was destroyed to decrease its counter.
+	 *
+	 * onDeleteCallback is called with *invalid* pointer.
+	 * ConnectionManager deletes Request first and then passes
+	 * the pointer to the callback. One may use the address
+	 * to find it in own HashMap or Array and remove it.
+	 * So, again, this pointer is for information only. One
+	 * cannot use it.
+	 */
+	struct RequestWithCallback {
 		Request *request;
-		RequestCallback callback;
+		RequestCallback onDeleteCallback;
 		
-		RequestWithCallback(Request *rq = nullptr, RequestCallback cb = nullptr): request(rq), callback(cb) {}
+		RequestWithCallback(Request *rq = nullptr, RequestCallback cb = nullptr): request(rq), onDeleteCallback(cb) {}
 	};
 
 	CURLM *_multi;	
@@ -78,6 +98,8 @@ public:
 	 *
 	 * If Request's state is RETRY, handleRetry() is called instead.
 	 *
+	 * The passed callback would be called after Request is deleted.
+	 *
 	 * @note This method starts the timer if it's not started yet.
 	 *
 	 * @return the same Request pointer, just as a shortcut
-- 
cgit v1.2.3