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

... / ...

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