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