From 4cb591b9dff36c47b3d55ef0f5f6d51bc1490f2e Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Tue, 30 Dec 2008 11:45:07 +0000
Subject: [PATCH] document Initialize/Shutdown()

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@57657 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 interface/wx/socket.h | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/interface/wx/socket.h b/interface/wx/socket.h
index d6cd5ccce9..ef5450411e 100644
--- a/interface/wx/socket.h
+++ b/interface/wx/socket.h
@@ -619,12 +619,9 @@ enum
     defines all basic IO functionality.
 
     @note
-    (Workaround for implementation limitation for wxWidgets up to 2.5.x)
-    If you want to use sockets or derived classes such as wxFTP in a secondary
-    thread, call @b wxSocketBase::Initialize() (undocumented) from the main
-    thread before creating any sockets - in wxApp::OnInit() for example.
-    See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
-    http://www.litwindow.com/knowhow/knowhow.html for more details.
+    When using wxSocket from multiple threads, even implicitly (e.g. by using
+    wxFTP or wxHTTP in another thread) you must initialize the sockets from the
+    main thread by calling Initialize() before creating the other ones.
 
     @beginEventTable{wxSocketEvent}
     @event{EVT_SOCKET(id, func)}
@@ -678,6 +675,34 @@ public:
     */
     bool Destroy();
 
+    /**
+        Perform the initialization needed in order to use the sockets.
+
+        This function is called from wxSocket constructor implicitly and so
+        normally doesn't need to be called explicitly. There is however one
+        important exception: as this function must be called from the main
+        (UI) thread, if you use wxSocket from multiple threads you must call
+        Initialize() from the main thread before creating wxSocket objects in
+        the other ones.
+
+        It is safe to call this function multiple times (only the first call
+        does anything) but you must call Shutdown() exactly once for every call
+        to Initialize().
+
+        @return
+            @true if the sockets can be used, @false if the initialization
+            failed and sockets are not available at all.
+     */
+    static bool Initialize();
+
+    /**
+        Shut down the sockets.
+
+        This function undoes the call to Initialize() and must be called after
+        every successful call to Initialize().
+     */
+    static void Shutdown();
+
     //@}