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