git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

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