Inheritance diagram for os::Looper:

Classes
class	Private

Public Types
typedef std::map< int, Handler * >	handler_map

Public Member Functions
	Looper (const String &cName, int nPriority=NORMAL_PRIORITY, int nPortSize=DEFAULT_PORT_SIZE)
	The looper constructor. More...

virtual	~Looper ()
	Looper destructor. More...

void	SetName (const String &cName)
	Rename the looper. More...

String	GetName () const
	Get the loopers name. More...

bool	IsPublic () const
	See if the looper's message port is public. More...

void	SetPublic (bool bPublic)
	Make port public/private. More...

port_id	GetMsgPort () const
	Obtain the low-level message port used by this looper. More...

thread_id	GetThread () const
	Obtain the thread id of the looper thread. More...

proc_id	GetProcess () const
	Obtain the process ID of the loopers thread. More...

status_t	Lock ()
	Lock the looper object. More...

status_t	Lock (bigtime_t nTimeout)
	Lock the looper with a timeout. More...

status_t	SafeLock ()
	Attempt to lock the looper. More...

status_t	Unlock ()
	Unlock the looper. More...

void	SetMutex (Locker *pcMutex)
	Set a custom mutex to be used by the looper. More...

Locker *	GetMutex () const
	Get a pointer to the loopers mutex. More...

int	GetLockCount () const
	Obtain the number of locks held on the looper. More...

thread_id	GetLockingThread () const
	Obtaing the owner of the looper lock. More...

bool	IsLocked () const
	Check if the looper lock is owned by the calling thread. More...

virtual thread_id	Run ()
	Start and unlock the looper. More...

int	Wait () const
	Wait for the looper thread to die. More...

status_t	PostMessage (uint32 nCode)
	Deliver a message to the looper. More...

status_t	PostMessage (Message *pcMsg)
	Deliver a message to the looper. More...

status_t	PostMessage (uint32 cCode, Handler pcHandler, Handler pcReplyTo=NULL)
	Deliver a message to the looper. More...

status_t	PostMessage (Message pcMsg, Handler pcHandler, Handler *pcReplyTo=NULL)
	Deliver a message to the looper. More...

void	SpoolMessages ()
	Drain the low-level message port. More...

Message *	GetCurrentMessage () const
	Obtain the message currently being processed. More...

Message *	DetachCurrentMessage ()
	Steal the current message. More...

virtual void	DispatchMessage (Message pcMessage, Handler pcHandler)
	The loopers message handling callback. More...

virtual void	Started ()
	Called by the looper thread before entering the message loop. More...

virtual bool	Idle ()
	Hook called each time the message queue is drained. More...

MessageQueue *	GetMessageQueue () const
	Obtain the internal message queue used by the looper. More...

virtual bool	OkToQuit ()
	Check if it is ok to break the loop. More...

virtual void	Quit ()
	Unconditionally terminate the looper. More...

void	Terminate ()
	Unconditionally terminate the looper. More...

void	AddTimer (Handler *pcTarget, int nID, bigtime_t nTimeout, bool bOneShot=true)
	Add a timer to the looper. More...

bool	RemoveTimer (Handler *pcTarget, int nID)
	Delete a timer. More...

const handler_map &	GetHandlerMap () const
	Get the internal handler list. More...

void	AddHandler (Handler *pcHandler)
	Add a handler to the looper. More...

bool	RemoveHandler (Handler *pcHandler)
	Remove a handler previously added by AddHandler() More...

Handler *	FindHandler (const String &cName) const
	Search the looper for a named handler. More...

int	GetHandlerCount () const
	Obtain the count of handlers added to this looper. More...

void	SetDefaultHandler (Handler *pcHandler)
	Set the default target for incomming messages. More...

Handler *	GetDefaultHandler () const
	Obtain the default handler for the looper. More...

void	AddCommonFilter (MessageFilter *pcFilter)

void	RemoveCommonFilter (MessageFilter *pcFilter)

const MsgFilterList &	GetCommonFilterList () const

Public Member Functions inherited from os::Handler
	Handler (const String &cName)
	Construct a handler. More...

virtual	~Handler ()
	Destructor. More...

virtual void	TimerTick (int nID)
	Timer dispatch member. More...

virtual void	HandleMessage (Message *pcMessage)
	Handle a message targeted at this handler. More...

String	GetName () const
	Get the handlers name. More...

void	SetName (const String &cName)
	Rename the handler. More...

Looper *	GetLooper () const
	Get a pointer to the looper this handler belongs to. More...

void	SetNextHandler (Handler *pcNextHandler)
	Set a handler that should handle messages this handler is not interrested in. More...

Handler *	GetNextHandler () const
	Get the next handler in a handler chain. More...

void	AddFilter (MessageFilter *pcFilter)

void	RemoveFilter (MessageFilter *pcFilter)

const MsgFilterList &	GetFilterList () const

const uint32	GetToken ()
	Get the handlers token. More...

Static Public Member Functions
static Looper *	GetLooperForThread (thread_id hThread)

Protected Member Functions
bool	FilterMessage (Message pcMsg, Handler ppcTarget, std::list< MessageFilter > *pcFilterList)

Friends
class	Application

class	Messenger

class	NodeMonitor

class	Window

Detailed Description

Description:

See Also

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Member Typedef Documentation

typedef std::map<int,Handler*> os::Looper::handler_map

Constructor & Destructor Documentation

Looper::Looper	(	const String &	cName,
		int	nPriority = `NORMAL_PRIORITY`,
		int	nPortSize = `DEFAULT_PORT_SIZE`
	)

Description:: This is the only Looper constructor. It initiates the looper and create the needed message port and message queue but it does not spawn a new thread. To actually start the message loop you must call Run(). Before the constructor returns it will lock the looper by calling Lock(). This means that before any other threads are able to access it you must call Unlock().

Parameters

pzName	Passed down to the Handler::Handler() constructor.
nPriority	Stored for later usage as the looper-thread priority.
nPortSize	Maximum number of pending messages.

See Also: Handler::Handler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References AddHandler(), Lock(), os::Looper::Private::m_hPort, os::Looper::Private::m_hThread, os::Looper::Private::m_nID, os::Looper::Private::m_nNextEvent, os::Looper::Private::m_nPriority, os::Looper::Private::m_pcCurrentMessage, os::Looper::Private::m_pcDefaultHandler, os::Looper::Private::m_pcFirstRestartTimer, os::Looper::Private::m_pcFirstTimer, and os::Looper::Private::m_pcMsgQueue.

Looper::~Looper ( )

virtual

Description:: Free all resources allocated by the looper.

Note: You shold normally not delete a looper with the "delete" operator. The looper thread will delete the object itself before it terminates. To get rid of a looper you should terminate it by calling Quit() or by sending it a M_QUIT message.

: In some very rare cases it is still possible to delete the looper which is why the destructor is not private. If you just create the looper but never call Run() it is safe to delete the object. After calling Run() the looper thread are responsible for the looper object and deleting it will cause the application to crash!

See Also: Looper::Looper()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_hPort, os::Looper::Private::m_pcFirstRestartTimer, os::Looper::Private::m_pcFirstTimer, os::Looper::Private::m_pcMsgQueue, and RemoveHandler().

Member Function Documentation

void Looper::AddCommonFilter ( MessageFilter * pcFilter )

References os::Looper::Private::m_cCommonFilterList, RemoveCommonFilter(), and os::Handler::RemoveFilter().

void Looper::AddHandler ( Handler * pcHandler )

Description:: Adds a handler to the looper. In order to receive messages and before it can be set as a default handler the handler must be added to a looper. The handler must not be member of any looper when added.

Parameters

pcHandler - Pointer to the handler to be added.

See Also: RemoveHandler(), SetDefaultHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cHandlerMap, and os::Looper::Private::m_pcMutex.

Referenced by Looper().

void Looper::AddTimer	(	Handler *	pcTarget,
		int	nID,
		bigtime_t	nPeriode,
		bool	bOneShot = `true`
	)

Description:: Timers should be employed when you have a small task that should be run periodically or that you would like to schedule some point ahead in time. A timer is targeted at a spesific handler and will cause the os::Handler::TimerTick() member to be called each time the timer expire. You can add an arbritary number of timers to a looper.

: The Handler::TimerTick() will be called by the looper thread with the looper locked.

Note: As with every callbacks from the looper thread, you should not do any long-lasting computing in the os::Handler::TimerTick() function. The looper will not be able to handle any messages until the function returns. This can cause the application to feel unresponsive. If you have any long-lasting tasks, you hould spawn a new thread to get the job done.

Parameters

pcTarget	Must be a valid ponter to a handler belonging to this looper. This is the handler that will get it's TimerTick() member called.
nID	An user defined ID that is passed to the TimerTick() function to make it possible to distinguish different timers.
nPeriode	Time in micro seconds before the timer fires. If not in one-shot mode, the timer will be rescheduled with the same delay until manually removed.
bOneShot	If true the timer will fire once, and then be removed. If false the timer will be continually rescheduled until removed by Looper::RemoveTimer().

See Also: RemoveTimer(), os::Handler::TimerTick()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References RemoveTimer().

Referenced by os::ScrollBar::MouseDown(), os::ScrollBar::MouseMove(), os::ToolTip::ShowTip(), os::IconView::StartScroll(), and os::ScrollBar::TimerTick().

Message * Looper::DetachCurrentMessage ( )

Description:: GetCurrentMessage() does basically the same job as GetCurrentMessage() except that it detatch the message from the looper, preventing it from being automatically deleted. You are responsible of getting rid of the message when it is no longer needed.

Returns: Pointer to a message, or NULL if no message is currently being processed.

See Also: GetCurrentMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcCurrentMessage.

void Looper::DispatchMessage	(	Message *	pcMsg,
		Handler *	pcHandler
	)

virtual

Description:: When a message arrives, the looper extract's it from the queue and call this member with the message as a parameter. The default implementation will attempt to pass the message on to a Handler through it's os::Handler::HandleMessage() member. The Handler that should receive the message is selected as follows:

: If the message targets a specific Handler, that Handler will receive the message. DispatchMessage() can determine wether the message had a final destination by examining the pcHandler argument. If not NULL it points at the handler targeted by the message.

: If the message destination however is not fully qualified DispatchMessage() attempts to pass the message on to the Default handler (as set through the SetDefaultHandler()).

: If there is no final destination and no default handler the Looper will handle the message itself by calling its own version of HandleMessage() (The looper is itself a os::Handler)

: Not all messages are passed on to a handler. If the message code is M_QUIT the Looper::OkToQuit() member is called instead and if it return true looper object will be deleted and the looper thread terminated.

: If you would like to handle certain messages directly by the looper, bypassing the normal scheduling you can overload DispatchMessage() to process messages before they are passed on to any handler. If you do so, you should call the loopers version of DispatchMessage() for each message you don't know how to handle.

: Please note however that you should very rarly overload this member. It is normaly better to overload the HandleMessage() member and let the looper handle the message as any other handlers if you want to pass messages to the looper itself.

Note: The looper is locked when DispatchMessage() is called.; Never do any lengthy operations in any hook members that are called from the looper thread if the looper is involved with the GUI (for example if the looper is a os::Window). The looper will not be able to dispatch messages until the hook returns so spending a long time in this member will make the GUI feel unresponsive.

Parameters

pcMsg	- Pointer to the received messge. Note that this message will be deleted when DispatchMessage() returns, unless detatched from the looper through DetachCurrentMessage().
pcHandler	- Pointer to the handler targeted by this message. If the message was not targeted at any spesific handler this argument is NULL.

See Also: SetDefaultHandler(), GetDefaultHandler(), PostMessage(), GetCurrentMessage(); DetachCurrentMessage(), Handler::HandleMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::Window.

References FilterMessage(), os::Message::GetCode(), os::Handler::HandleMessage(), os::Looper::Private::m_pcDefaultHandler, os::M_QUIT, OkToQuit(), and Unlock().

Referenced by os::Window::DispatchMessage().

bool Looper::FilterMessage	(	Message *	pcMsg,
		Handler **	ppcTarget,
		std::list< MessageFilter * > *	pcFilterList
	)

protected

References os::MF_DISCARD_MESSAGE, and os::MF_DISPATCH_MESSAGE.

Referenced by DispatchMessage().

Handler * Looper::FindHandler ( const String & cName ) const

Description:: Return the handler named <pzName>, or NULL if there is no such handler added to the looper.

Parameters

pzName The name to search for.

Returns: Pointer to the handler if one was found, NULL otherwise

See Also: GetHandler(), GetHandlerCount(), GetHandlerIndex(); AddHandler(), RemoveHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), os::Looper::Private::m_cHandlerMap, and os::Looper::Private::m_pcMutex.

const MsgFilterList & Looper::GetCommonFilterList ( ) const

References os::Looper::Private::m_cCommonFilterList.

Message * Looper::GetCurrentMessage ( ) const

Description:: This member can be called from within os::Looper::DispatchMessage() or the active handlers os::Handler::HandleMessage() to learn whitch message is currently being processed. Given the fact that the very same message is passed to both this members you may wonder why you should ever need to call this function? The reason is that many of the classes derived from either os::Looper or os::Handler will convert known messages to specialized callbacks. These callbacks are normally not passed the entire message, only the most used elements. If you should find yourself in the unlucky situation of needing one of the not so much used elements this member is the solution.

Note: The message will be automatically deleted when you return to the message loop. To avoid this you should use Looper::DetachCurrentMessage() instead.

: Called outside the message loop this member will return NULL.

Returns: Pointer to a message, or NULL if no message is currently being processed.

See Also: DetachCurrentMessage(), DispatchMessage(), Handler::HandleMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcCurrentMessage.

Referenced by os::IconDirectoryView::KeyDown().

Handler * Looper::GetDefaultHandler ( ) const

Description:: Return the handler last set by SetDefaultHandler() or NULL if there currently is no default handler

Returns: Pointer to the default handler.

See Also: SetDefaultHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcDefaultHandler.

int Looper::GetHandlerCount ( ) const

Returns: Number of handlers currently attached to the looper

See Also: GetHandler(), AddHandler(), RemoveHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cHandlerMap.

const Looper::handler_map & Looper::GetHandlerMap ( ) const

Description:: You can use this member to gain read-only access to the internal stl map of handlers. The map key is an unique ID that is assigned to each handler in the system (unique accross process boundaries). This ID should be considered a implemntation detail and are of no value outside the looper/handler implemntation itself. You can still traverse the map to examine the handlers that currently populate the looper. You should always keep the looper locked while examining the map.

Returns: const reference to the internal stl map of handlers.

See Also: FindHandler(), AddHandler(), RemoveHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cHandlerMap.

int Looper::GetLockCount ( ) const

Description:: Return the nest count (number of locks held by the owner) from the internal mutex used to protect the looper.

Warning:: This function is dangerous in that it is very hard to use without encountering race condition and are generally not very useful. The reason for including it is that it in some cases can be a useful help when debuggin a looper.

Returns: Loopers lock nest count.

See Also: Lock(), SafeLock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::GetLockCount(), and os::Looper::Private::m_pcMutex.

thread_id Looper::GetLockingThread ( ) const

Description:: Returns the thread ID of the thread currently holding the looper lock. If the looper is not locked, -1 is returned.

Warning:: This function is dangerous in that it is very hard to use without encountering race condition and are generally not very useful. The reason for including it is that it in some cases can be a useful help when debuggin a looper.

Returns: The thread ID of the lock owner or -1 if the looper is not locked.

See Also: GetLockCount(), Lock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::GetOwner(), and os::Looper::Private::m_pcMutex.

static Looper* os::Looper::GetLooperForThread ( thread_id hThread )

inlinestatic

MessageQueue * Looper::GetMessageQueue ( ) const

Description:: You should rarely need to examine the message queue yourself but it can be useful in certain situations. For example some messages might comes in such an overwelming amount and are of a nature that you can miss some of them without any harm. It is then useful to be able to look through the message queue when such a message arrive to check if there is more of them waiting and if so throw away the current message, and wait for the next to crawl its way down the queue. One example of such messages are the M_MOUSE_MOVED message. You will propably call SpoolMessages() before calling this message (but after locking the looper) to make sure the queue contains all messages sent to the looper.

Returns: A pointer to the internal MessageQueue object used by the looper.

See Also: DispatchMessage(), PostMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcMsgQueue.

Referenced by os::Window::DispatchMessage(), os::IconDirectoryView::ReRead(), and os_priv::DirKeeper::Stop().

port_id Looper::GetMsgPort ( ) const

Description:: Obtain the low-level message port used by this looper.

Returns: The port ID of the internal message port.

See Also: GetMessageQueue(), GetCurrentMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_hPort.

Locker * Looper::GetMutex ( ) const

Description:: Returns the currently active mutex. This is normally a internal os::Locker object allocated by the looper itself but if the mutex has been replaced with SetMutex() the new mutex will be returned.

Returns: Pointer to the mutex currently used to protect the looper.

See Also: SetMutex(), Lock(), Unlock(), os::Locker

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcMutex.

String Looper::GetName ( ) const

Description:: Get the looper name as set by the constructor or the SetName() member.

Returns: The loopers name.

See Also: SetName()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cName.

Referenced by os::Settings::Private::GetAppName(), os::Application::RegisterKeyEvent(), os::Application::UnregisterKeyEvent(), and os::Application::~Application().

proc_id Looper::GetProcess ( ) const

Description:: Obtain the process ID of the loopers thread.

Returns: A valid process ID if the loop is running, -1 otherwise.

See Also: GetThread()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_hThread.

thread_id Looper::GetThread ( ) const

Description:: Obtain the thread id of the looper thread.

Returns: A valid thread ID if the loop is running, -1 otherwise.

See Also: GetProcess()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_hThread.

Referenced by os::Message::SendReply().

bool Looper::Idle ( )

virtual

Description:: Normally the looper thread is blocked on the internal message queue waiting for messages. When one or more messages arrive it will wake up and process the messages. When all messages is processed it will first call Idle() and then go back looking for more messages. If Idle() returned false the thread will block until the next message arrive and if Idle() returned true it will just look for new messages without blocking and call Idle() again (after processing new messages if any).

Note:: The looper will not be able to process new messages until Idle() returns so it is very important to not do anything lengthy if the looper is part of for example an os::Window since that will make the application feel "unresponcive" to the user.

Returns: The Idle() function should return true if it want to be called again imediatly after the looper has polled for new messages, or false if it don't want to be called until at least one more message has been processed.

See Also: HandleMessage(), DispatchMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os_priv::DirKeeper.

bool Looper::IsLocked ( ) const

Description:: Check if the looper lock is owned by the calling thread.

Warning:: I can't think of any safe usage of this function, other than as a debugging aid.

Returns

See Also: Lock(), SafeLock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::IsLocked(), and os::Looper::Private::m_pcMutex.

bool Looper::IsPublic ( ) const

Description:: Retur

Returns: True if the message port is public, false otherwise.

See Also: SetPublic()

Author: Henrik Isaksson (henri.nosp@m.k@is.nosp@m.aksso.nosp@m.n.tk)

References os::Looper::Private::m_hPort.

status_t Looper::Lock ( )

Description:: Before calling almost any other function on a looper or one of it's derived classes, you must lock it by calling this member. You can nest calls to Lock() within the same thread, each call to Lock() will then require a corresponding call to Unlock() to release the looper.

: Looper::Lock() will not be affected by singnals that don't kill the thread. It will keep on retrying until it succed, or the failure was to someting else than a signal.

Note: You should avoid keeping the looper locked for an extended periode of time since that will prevent it from handling any messages and can cause the application to feel unresponsive.

Returns: Return 0, unless someting realy bad happened.

See Also: SafeLock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::Lock(), and os::Looper::Private::m_pcMutex.

Referenced by os::FileRequester::FileRequester(), os::Application::GetQualifiers(), Looper(), MoveFileThread(), OperationCopyFile(), os::ProgressRequester::ProgressRequester(), os::IconDirectoryView::ReRead(), MountDialogScanner::Run(), SafeLock(), MountDialogScanner::ScanPath(), os::Application::SetCatalog(), os_priv::DirKeeper::Stop(), and os::Application::~Application().

status_t Looper::Lock ( bigtime_t nTimeout )

Description:: Lock the looper with a timeout. Like Lock() this member will attempt to acquire the loopers mutex but this version will only wait nTimeout micro seconds before timing out and fail with errno==ETIME.

Note: Unlike the regular Lock() member this member will fail with errno==EINTR if the thread receive a POSIX signal while waiting to aquire the mutex or with errno==ETIME if the timeout is reached.

Warning:

Parameters

nTimeout Maximum number of micro seconds to wait for the looper mutex to be available.

Returns: On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.

Error codes:

EINTR An unignored POSIX signal was received. ETIME The timeout expired before the mutex could be aquired.

See Also: Lock(), SafeLock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::Lock(), and os::Looper::Private::m_pcMutex.

bool Looper::OkToQuit ( void )

virtual

Description:: You can overload this function to affect how the looper will react to M_QUIT messages. When an M_QUIT message arrive the looper will call this function to figure out what to do. If it returns false the message is ignored. If it returns true the loop is terminated, the looper object deleted and the looper thread will exit.

Returns: true if it is ok to terminate the looper, false otherwise.

See Also: Quit(), PostMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in HandlerSelector, os::FontRequester, os::InputBox, os::ColorRequester, os::FileRequester, and os::Splash.

Referenced by DispatchMessage().

status_t Looper::PostMessage ( uint32 nCode )

Description:: Construct a message with the given code, and posts it to the looper by calling PostMessage( Message* pcMsg )

Parameters

nCode The code that should be assigned to the sendt message

Returns: 0 if everyting went ok. If someting went wrong, a negative number is retuned, and the errno variable is set.

See Also: PostMessage( Message* pcMsg ),DispatchMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::IconDirectoryView::DetachedFromWindow(), os::Alert::Go(), os::Handler::HandleMessage(), os::DropdownMenu::HandleMessage(), os::Alert::HandleMessage(), os::IconDirectoryView::HandleMessage(), os::IconDirectoryView::KeyDown(), MoveFileThread(), os::Splash::OkToQuit(), PostMessage(), os::RegistrarManager::Put(), os::IconDirectoryView::ReRead(), os::MenuWindow::ShutDown(), Terminate(), os::DropdownMenu::WheelMoved(), and os::DropdownMenu::~DropdownMenu().

status_t Looper::PostMessage ( Message * pcMsg )

Description:: The message is posted to the looper with no absolute destination. This means that it will be handled by the default handler or the looper itself if there currently is no default handler.

Note:: The caller is responsible for deleting the message (It is not deleted or kept by the looper)

Parameters

pcMsg The message to post.

Returns: 0 if everyting went ok. If someting went wrong, a negative number is retuned, and the errno variable is set.

See Also: DispatchMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References GetMsgPort().

status_t Looper::PostMessage	(	uint32	nCode,
		Handler *	pcHandler,
		Handler *	pcReplyTo = `NULL`
	)

Description:: Construct a message with the given code, and posts it to a specific handler by calling PostMessage( Message pcMsg, Handler *pcHandler, Handler pcReplyHandler )

Parameters

nCode	The code that should be assigned to the sendt message
pcHandler	Must point to a valid handler that will receive the message.
pcReplyTo	If not NULL should point to the handler that should receive the reply sendt to the message.

Returns: 0 if everyting went ok. If someting went wrong, a negative number is retuned, and the errno variable is set.

See Also: PostMessage( Message pcMsg, Handler *pcHandler, Handler pcReplyHandler ); DispatchMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References PostMessage().

status_t Looper::PostMessage	(	Message *	pcMsg,
		Handler *	pcHandler,
		Handler *	pcReplyHandler = `NULL`
	)

Description:: Post a message to a specific handler. The message is targeted to the handler pointed at by pcHandler, and the reply is set to the handler pointed at by pcReplyTo.

Note:: The caller is responsible for deleting the message (It is not deleted or kept by the looper)

: You may not pass NULL as the target, but you can send a pointer to the looper itself to force it to handle the message.

Parameters

nCode	The code that should be assigned to the sendt message
pcHandler	Must point to a valid handler that will receive the message.
pcReplyTo	If not NULL should point to the handler that should receive the reply sendt to the message.

Returns: 0 if everyting went ok. If someting went wrong, a negative number is retuned, and the errno variable is set.

See Also: PostMessage( Message* pcMsg ), DispatchMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Handler::GetLooper(), and GetMsgPort().

void Looper::Quit ( )

virtual

Description:: Calling quit will unconditionally terminate the looper (As opposed to posting an M_QUIT message that will politly call OkToQuit() before terminating the looper). If the call is made by the looper thread itself this member will delete the looper object, and call exit_thread(). If an external thread made the call, a M_TERMINATE message is sent, and the caller thread is blocked until the looper thread is dead. Either way the looper object gets deleted, and the looper thread dies.

Deprecated:: Use Terminate() instead.

See Also: OkToQuit(), PostMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References Terminate().

void Looper::RemoveCommonFilter ( MessageFilter * pcFilter )

References os::Looper::Private::m_cCommonFilterList.

Referenced by AddCommonFilter().

bool Looper::RemoveHandler ( Handler * pcHandler )

Description:: Removes a handler from the looper. If the default handler is removed the default looper pointer as returned by GetDefaultHandler() will be set to NULL.

Parameters

pcHandler The handler to remove

Returns: True if the Handler in fact was a member of the looper, false otherwise.

See Also: AddHandler(), SetDefaultHandler(), GetDefaultHandler()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cHandlerMap, os::Looper::Private::m_pcDefaultHandler, and os::Looper::Private::m_pcMutex.

Referenced by os::Handler::~Handler(), and ~Looper().

bool Looper::RemoveTimer	(	Handler *	pcTarget,
		int	nID
	)

Description:: When creating a timer in repeate mode you will propably at some time want to get rid of it. This is the way to go.

Parameters

-	pcTarget - The handler for which a timer is to be removed.
-	nID - The ID of the timer to be removed.

Returns: True if the timer was found, false otherwise.

See Also: AddTimer(), Handler::TimerTick()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcFirstRestartTimer, and os::Looper::Private::m_pcFirstTimer.

Referenced by AddTimer(), os::ScrollBar::MouseMove(), os::ScrollBar::MouseUp(), and os::IconView::StopScroll().

thread_id Looper::Run ( void )

virtual

Description:: As mention in the description of the constructor, no thread are spawned there and the looper is locked. Calling Run() will spawn a new thread to run the message loop, and unlock the looper.

Note:: Not all loopers will spawn a new thread. Ie. the Application class will overload the Run() member and lead the calling thread into the message loop. This means that when calling Run() on an application object it will not return until the loop terminates.

Returns: The thread ID of the looper thread.

See Also: Quit(), OkToQuit(), PostMessage(), Lock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::Application.

References os::String::c_str(), os::Locker::Lock(), os::Looper::Private::m_cName, os::Looper::Private::m_hThread, os::Looper::Private::m_nPriority, os::Locker::Unlock(), and Unlock().

Referenced by os::IconDirectoryView::AttachedToWindow(), os::RegistrarManager::Get(), os::Window::Show(), and os::Window::Start().

status_t Looper::SafeLock ( )

Description:: SafeLock() have the same semantics as Lock() except that it verifies that the looper object is valid before attempting to lock it.

: A common problem when locking a looper from an external thread is that the looper might terminate and become invalid between the time you obtain a pointer to it and the time you call Lock(). This makes it impossible to lock a looper with Lock() from anything but the loopers own thread unless you have some other mechanism in place that guarantee that the looper will not go away before it is properly locked.

: SafeLock() will verify that the looper is valid and lock it in a atomic fasion thus solving this problem. Note that this is much more expensive than the regular Lock() method so you should think twice before calling SafeLock().

Note: When communicating between two loopers it is often better to do so asyncronously through messages than by locking the peer and do direct member calls.

Returns: On success 0 is returned. On error -1 is returned and an error code is written to the global variable errno.

Error codes:

EINVAL SafeLock() was called on an invalid looper.

See Also: Lock(), Unlock()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Locker::Lock(), Lock(), os::Looper::Private::m_nID, and os::Locker::Unlock().

Referenced by os::Messenger::LockTarget(), and Terminate().

void Looper::SetDefaultHandler ( Handler * pcHandler )

Description:: Call this method to assign a handler as the default handler for the looper. When a handler become the default handler it will receive all messages that is not target directly at another handler. You can remove the current default handler by passing in a NULL pointer.

Note: The handler must already be added to this looper with AddHandler() before it can be made the default handler of the looper.

Parameters

pcHandler The handler to set as default, or NULL

See Also: GetDefaultHandler(), DispatchMessage(), Handler::HandleMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_pcDefaultHandler, and os::Looper::Private::m_pcMutex.

Referenced by os::Window::SetFocusChild().

void Looper::SetMutex ( Locker * pcMutex )

Description:: Each looper own a mutex that is used to protect the looper object against other threads. Normally this mutex is handled entirely internally by the looper and is only accesses indirectly through the various Lock() and Unlock() members. In some very rare cases it might be necessarry to control this mutex from the application.

: One possible usage for this is to "link" two loopers together to give the impression that they are both run by a single thread. By fetching the mutex from one looper with GetMutex() and passing it to another looper through SetMutex() (or by creating a new semaphore and give it to both the loopers) you will assure that the two looper threads will never run simultanously. This should very rarly be used in native AtheOS application as it will cripple the concurrency you normally gain by using multiple loopers but it might sometimes be defendable. For example when porting applications from a singlethreaded environment it can often be very hard to rewrite all the code to work with multiple threads. Then SetMutex() is a possible way to chicken-out of the heavy multithreading normally employed by AtheOS.

: In any case you should think twice before using this method. If you still think calling SetMutex() is a exellent idea think again.

Note: The looper will automatically lock the looper before calling any event handlers (like os::Looper::DispatchMessage(), os::Handler::HandleMessage, and os::Handler::TimerTick) and unlock it again when the event handler return. If you replace the mutex from one of these members you must make sure the new mutex is locked exactly once so it will be unlocked correctly when the method returns.

: You must also make sure that you don't introduce any race conditions with other threads as a result of the swap.

Note: The mutex object will not be deleted when the looper dies. You are responsible to get rid of it after (but only after) the looper is dead. Also note that if you lend the internal mutex from one looper to another the second looper will be left high and dry if the first looper dies and delete it's internal semaphore.

Parameters

pcMutex Pointer to the new mutex object or NULL to restore the default mutex

See Also: GetMutex(), Lock(), Unlock(), os::Locker

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_cDefaultMutex, and os::Looper::Private::m_pcMutex.

Referenced by os::Menu::Open(), and os::Menu::Track().

void Looper::SetName ( const String & cName )

Description:: Rename the looper. If the looper is already started the looper-thread will be renamed aswell. If there is no looper-thread yet the name will be remembered and will be used as the thread-name when the looper is started.

: The looper names is mostly used for debugging and does not need to be unique.

Parameters

cName The new looper name

See Also: GetName()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), os::Looper::Private::m_cName, and os::Looper::Private::m_hThread.

void Looper::SetPublic ( bool bPublic )

Description:: SetPublic() is used to decide whether the Looper's message port is to be public or not. A public message port can be accessed by other processes that only need to know the name of the message port.

See Also: IsPublic(), os::Messenger

Author: Henrik Isaksson (henri.nosp@m.k@is.nosp@m.aksso.nosp@m.n.tk)

References os::Looper::Private::m_hPort.

void Looper::SpoolMessages ( )

Description:: SpoolMessage() will fetch all messages from the low-level message port deflatten the message objects, and add the os::Message objects to the internal message queue

See Also: GetMessageQueue(), PostMessage()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Looper::Private::m_hPort.

Referenced by os::Window::DispatchMessage(), os::IconDirectoryView::ReRead(), and os_priv::DirKeeper::Stop().

void Looper::Started ( )

virtual

Description:: This hook can be overloaded to do one-shot initialization of the looper that can not be done in the contructor. Started() is called from the loopers thread just before it starts processing messages.

See Also: Idle(), Run()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

void Looper::Terminate ( )

Description:: Calling quit will unconditionally terminate the looper (As opposed to posting an M_QUIT message that will politly call OkToQuit() before terminating the looper). If the call is made by the looper thread itself this member will delete the looper object, and call exit_thread(). If an external thread made the call, a M_TERMINATE message is sent, and the caller thread is blocked until the looper thread is dead. Either way the looper object gets deleted, and the looper thread dies.