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

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/msgqueue.h
	3	// Purpose: interface of wxMessageQueue<T>
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows licence
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	Error codes for wxMessageQueue<> operations.
	11
	12	This enum contains the possible return value of wxMessageQueue<> methods.
	13
	14	@since 2.9.0
	15	@category{threading}
	16	*/
	17	enum wxMessageQueueError
	18	{
	19	/// Indicates that the operation completed successfully.
	20	wxMSGQUEUE_NO_ERROR = 0,
	21
	22	/**
	23	Indicates that no messages were received before timeout expired.
	24
	25	This return value is only used by wxMessageQueue<>::ReceiveTimeout().
	26	*/
	27	wxMSGQUEUE_TIMEOUT,
	28
	29	/// Some unexpected (and fatal) error has occurred.
	30	wxMSGQUEUE_MISC_ERROR
	31	};
	32
	33	/**
	34	wxMessageQueue allows passing messages between threads.
	35
	36	This class should be typically used to communicate between the main and worker
	37	threads. The main thread calls wxMessageQueue::Post and the worker thread
	38	calls wxMessageQueue::Receive.
	39
	40	@tparam T
	41	For this class a message is an object of arbitrary type T.
	42
	43	Notice that often there is a some special message indicating that the thread
	44	should terminate as there is no other way to gracefully shutdown a thread
	45	waiting on the message queue.
	46
	47	@since 2.9.0
	48
	49	@nolibrary
	50	@category{threading}
	51
	52	@see wxThread
	53	*/
	54	template <typename T>
	55	class wxMessageQueue<T>
	56	{
	57	public:
	58	/**
	59	Default and only constructor.
	60	Use wxMessageQueue::IsOk to check if the object was successfully initialized.
	61	*/
	62	wxMessageQueue();
	63
	64	/**
	65	Remove all messages from the queue.
	66
	67	This method is meant to be called from the same thread(s) that call
	68	Post() to discard any still pending requests if they became
	69	unnecessary.
	70
	71	@since 2.9.1
	72	*/
	73	wxMessageQueueError Clear();
	74
	75	/**
	76	Returns @true if the object had been initialized successfully, @false
	77	if an error occurred.
	78	*/
	79	bool IsOk() const;
	80
	81	/**
	82	Add a message to this queue and signal the threads waiting for messages
	83	(i.e. the threads which called wxMessageQueue::Receive or
	84	wxMessageQueue::ReceiveTimeout).
	85
	86	This method is safe to call from multiple threads in parallel.
	87	*/
	88	wxMessageQueueError Post(T const& msg);
	89
	90	/**
	91	Block until a message becomes available in the queue.
	92	Waits indefinitely long or until an error occurs.
	93
	94	The message is returned in @a msg.
	95	*/
	96	wxMessageQueueError Receive(T& msg);
	97
	98	/**
	99	Block until a message becomes available in the queue, but no more than
	100	@a timeout milliseconds has elapsed.
	101
	102	If no message is available after @a timeout milliseconds then returns
	103	@b wxMSGQUEUE_TIMEOUT.
	104
	105	If @a timeout is 0 then checks for any messages present in the queue
	106	and returns immediately without waiting.
	107
	108	The message is returned in @a msg.
	109	*/
	110	wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
	111	};
	112