Documented nasty side effects of ipcache_nbgethostbyname.

diff --git a/src/ipcache.cc b/src/ipcache.cc
index 4a653029a7d190e2d34e515bb9ebfbc83a2a3bcf..74be02a7ebc3f3379beec3e859a9ec429b86a98a 100644 (file)
--- a/src/ipcache.cc
+++ b/src/ipcache.cc
@@ -681,6 +681,14 @@ ipcacheHandleReply(void *data, rfc1035_rr * answers, int na, const char *error_m
  \param handler                Pointer to the function to be called when the reply
  *                     from the IP cache (or the DNS if the IP cache misses)
  \param handlerData    Information that is passed to the handler and does not affect the IP cache.
+ *
+ * XXX: on hits and some errors, the handler is called immediately instead
+ * of scheduling an async call. This reentrant behavior means that the
+ * user job must be extra careful after calling ipcache_nbgethostbyname,
+ * especially if the handler destroys the job. Moreover, the job has 
+ * no way of knowing whether the reentrant call happened. commConnectStart
+ * protects the job by scheduling an async call, but some user code calls 
+ * ipcache_nbgethostbyname directly.
  */
 void
 ipcache_nbgethostbyname(const char *name, IPH * handler, void *handlerData)