added interface headers with latest discussed changes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/recguard.h

@@ -0,0 +1,97 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        recguard.h
+// Purpose:     documentation for wxRecursionGuardFlag class
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxRecursionGuardFlag
+    @wxheader{recguard.h}
+    
+    This is a completely opaque class which exists only to be used with 
+    wxRecursionGuard, please see the example in that
+    class documentation.
+    
+    Please notice that wxRecursionGuardFlag object must be declared 
+    @c static or the recursion would never be detected.
+    
+    @library{wxbase}
+    @category{FIXME}
+*/
+class wxRecursionGuardFlag 
+{
+public:
+    
+};
+
+
+/**
+    @class wxRecursionGuard
+    @wxheader{recguard.h}
+    
+    wxRecursionGuard is a very simple class which can be used to prevent reentrancy
+    problems in a function. It is not thread-safe and so should be used only in
+    single-threaded programs or in combination with some thread synchronization
+    mechanisms.
+    
+    wxRecursionGuard is always used together with the 
+    wxRecursionGuardFlag like in this example:
+    
+    @code
+    void Foo()
+        {
+            static wxRecursionGuardFlag s_flag;
+            wxRecursionGuard guard(s_flag);
+            if ( guard.IsInside() )
+            {
+                // don't allow reentrancy
+                return;
+            }
+    
+            ...
+        }
+    @endcode
+    
+    As you can see, wxRecursionGuard simply tests the flag value and sets it to
+    @true if it hadn't been already set. 
+    wxRecursionGuard::IsInside allows testing the old flag
+    value. The advantage of using this class compared to directly manipulating the
+    flag is that the flag is always reset in the wxRecursionGuard destructor and so
+    you don't risk to forget to do it even if the function returns in an unexpected
+    way (for example because an exception has been thrown).
+    
+    @library{wxbase}
+    @category{FIXME}
+*/
+class wxRecursionGuard 
+{
+public:
+    /**
+        A wxRecursionGuard object must always be initialized with a (static) 
+        wxRecursionGuardFlag. The constructor saves the
+        value of the flag to be able to return the correct value from 
+        IsInside().
+    */
+    wxRecursionGuard(wxRecursionGuardFlag& flag);
+
+    /**
+        The destructor resets the flag value so that the function can be entered again
+        the next time.
+        
+        Note that it is not virtual and so this class is not meant to be derived from
+        (besides, there is absolutely no reason to do it anyhow).
+    */
+    ~wxRecursionGuard();
+
+    /**
+        Returns @true if we're already inside the code block "protected'' by this
+        wxRecursionGuard (i.e. between this line and the end of current scope). Usually
+        the function using wxRecursionGuard takes some specific actions in such case
+        (may be simply returning) to prevent reentrant calls to itself.
+        
+        If this method returns @false, it is safe to continue.
+    */
+    bool IsInside();
+};