Pyro higlevel API
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
os::Looper Class Reference
Inheritance diagram for os::Looper:
os::Handler os::Application os::RegistrarManager os::Window os_priv::DirKeeper HandlerSelector InfoWin MountDialogWin NewDirWin os::Alert os::ColorRequester os::FileRequester os::FontRequester os::InputBox os::MenuWindow os::ProgressRequester os::Splash os::ToolTip RenameFileWin

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...
 
LockerGetMutex () 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...
 
MessageGetCurrentMessage () const
 Obtain the message currently being processed. More...
 
MessageDetachCurrentMessage ()
 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...
 
MessageQueueGetMessageQueue () 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_mapGetHandlerMap () 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...
 
HandlerFindHandler (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...
 
HandlerGetDefaultHandler () const
 Obtain the default handler for the looper. More...
 
void AddCommonFilter (MessageFilter *pcFilter)
 
void RemoveCommonFilter (MessageFilter *pcFilter)
 
const MsgFilterListGetCommonFilterList () 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...
 
LooperGetLooper () 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...
 
HandlerGetNextHandler () const
 Get the next handler in a handler chain. More...
 
void AddFilter (MessageFilter *pcFilter)
 
void RemoveFilter (MessageFilter *pcFilter)
 
const MsgFilterListGetFilterList () const
 
const uint32 GetToken ()
 Get the handlers token. More...
 

Static Public Member Functions

static LooperGetLooperForThread (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
pzNamePassed down to the Handler::Handler() constructor.
nPriorityStored for later usage as the looper-thread priority.
nPortSizeMaximum 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)
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
pcTargetMust be a valid ponter to a handler belonging to this looper. This is the handler that will get it's TimerTick() member called.
nIDAn user defined ID that is passed to the TimerTick() function to make it possible to distinguish different timers.
nPeriodeTime 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.
bOneShotIf 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
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
pzNameThe 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
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
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
nTimeoutMaximum 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
nCodeThe 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
pcMsgThe 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
nCodeThe code that should be assigned to the sendt message
pcHandlerMust point to a valid handler that will receive the message.
pcReplyToIf 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
nCodeThe code that should be assigned to the sendt message
pcHandlerMust point to a valid handler that will receive the message.
pcReplyToIf 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)
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
pcHandlerThe 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
pcHandlerThe 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
pcMutexPointer 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
cNameThe 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.
Note
The Looper is checked for validity, so it IS safe to call Terminate() on an invalid pointer.
See Also
OkToQuit(), PostMessage()

References os::Looper::Private::m_hThread, os::M_TERMINATE, PostMessage(), SafeLock(), and Unlock().

Referenced by Quit(), and os::Application::~Application().

status_t Looper::Unlock ( )
int Looper::Wait ( ) const
Description:
This member can be called from an external thread to wait for the looper thread to die.
Note
If this member return successfully it means that the looper is dead and no further members should be called on the looper object.
Returns
On success 0 is returned. On failure a negative value is returned and a error code is written to the global variable errno.
See Also
Run(), Quit()
Author
Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

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

Friends And Related Function Documentation

friend class Application
friend
friend class Messenger
friend
friend class NodeMonitor
friend
friend class Window
friend