← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/recguard.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/recguard.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        recguard.h
 
3
// Purpose:     interface of wxRecursionGuardFlag
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: recguard.h 64940 2010-07-13 13:29:13Z VZ $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/**
 
10
    @class wxRecursionGuardFlag
 
11
 
 
12
    This is a completely opaque class which exists only to be used with
 
13
    wxRecursionGuard, please see the example in that class' documentation.
 
14
 
 
15
    @remarks
 
16
 
 
17
    wxRecursionGuardFlag object must be declared @c static or the recursion
 
18
    would never be detected.
 
19
 
 
20
    @library{wxbase}
 
21
    @category{misc}
 
22
*/
 
23
class wxRecursionGuardFlag
 
24
{
 
25
public:
 
26
 
 
27
};
 
28
 
 
29
 
 
30
 
 
31
/**
 
32
    @class wxRecursionGuard
 
33
 
 
34
    wxRecursionGuard is a very simple class which can be used to prevent reentrancy
 
35
    problems in a function. It is not thread-safe and so should be used only in
 
36
    single-threaded programs or in combination with some thread synchronization
 
37
    mechanisms.
 
38
 
 
39
    wxRecursionGuard is always used together with the
 
40
    wxRecursionGuardFlag like in this example:
 
41
 
 
42
    @code
 
43
    void Foo()
 
44
    {
 
45
        static wxRecursionGuardFlag s_flag;
 
46
        wxRecursionGuard guard(s_flag);
 
47
        if ( guard.IsInside() )
 
48
        {
 
49
            // don't allow reentrancy
 
50
            return;
 
51
        }
 
52
 
 
53
        ...
 
54
    }
 
55
    @endcode
 
56
 
 
57
    As you can see, wxRecursionGuard simply tests the flag value and sets it to
 
58
    @true if it hadn't been already set.
 
59
    IsInside() allows testing the old flag
 
60
    value. The advantage of using this class compared to directly manipulating the
 
61
    flag is that the flag is always reset in the wxRecursionGuard destructor and so
 
62
    you don't risk to forget to do it even if the function returns in an unexpected
 
63
    way (for example because an exception has been thrown).
 
64
 
 
65
    @library{wxbase}
 
66
    @category{misc}
 
67
*/
 
68
class wxRecursionGuard
 
69
{
 
70
public:
 
71
    /**
 
72
        A wxRecursionGuard object must always be initialized with a @c static
 
73
        wxRecursionGuardFlag. The constructor saves the
 
74
        value of the flag to be able to return the correct value from
 
75
        IsInside().
 
76
    */
 
77
    wxRecursionGuard(wxRecursionGuardFlag& flag);
 
78
 
 
79
    /**
 
80
        The destructor resets the flag value so that the function can be entered again
 
81
        the next time.
 
82
 
 
83
        @note This is not virtual, so this class is not meant to be derived
 
84
              from (besides, there is absolutely no reason to do it anyhow).
 
85
    */
 
86
    ~wxRecursionGuard();
 
87
 
 
88
    /**
 
89
        Returns @true if we're already inside the code block "protected" by this
 
90
        wxRecursionGuard (i.e. between this line and the end of current scope).
 
91
        Usually the function using wxRecursionGuard takes some specific actions
 
92
        in such case (may be simply returning) to prevent reentrant calls to itself.
 
93
 
 
94
        If this method returns @false, it is safe to continue.
 
95
    */
 
96
    bool IsInside() const;
 
97
};
 
98