ac9714d8a4
The biggest change is the addition of \since to each method. I've gone through old versions of the BeBook and documented what version of BeOS each method was introduced in. I'm only counting production releases so I'm starting with BeOS R3 ignoring all DR and PR releases. Likewise, all methods new to Haiku are listed as being introduced \since Haiku R1 ignoring alpha releases.
947 lines
26 KiB
Plaintext
947 lines
26 KiB
Plaintext
/*
|
|
* Copyright 2008-2014 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Niels Sascha Reedijk, niels.reedijk@gmail.com
|
|
* John Scipione, jscipione@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/app/Looper.h hrev47355
|
|
* src/kits/app/Looper.cpp hrev47355
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Looper.h
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Provides the BLooper class.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_LOOPER_PORT_DEFAULT_CAPACITY
|
|
\brief The default size of the port of a BLooper.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BLooper
|
|
\ingroup app
|
|
\ingroup libbe
|
|
\brief Receive and process messages in a separate thread.
|
|
|
|
When an object of this class is created, the message loop can be started
|
|
with Run(). This spawns the thread that receives messages and processes
|
|
messages. Messages are actually passed on to \link BHandler handlers \endlink
|
|
that are associated with this looper. By default there is always one
|
|
handler available: the looper itself. To 'quit' a looper, you should pass
|
|
a \c B_QUIT_REQUESTED message using one of the message post functions. When
|
|
a looper receives such a request, it will \b delete itself. As such, looper
|
|
should <em>always be created on the heap</em> (with \c new), and never on
|
|
the stack.
|
|
|
|
Posting messages can be done using the various PostMessage() methods.
|
|
Whenever a message is posted, it will be added through to the message
|
|
queue. It is possible to apply filters (see AddCommonFilter()) to filter
|
|
out any messages that correspond with certain criteria. The method will
|
|
copy the contents of the message and this copy is processed, so make sure
|
|
you delete the original messages in case you create them on the heap.
|
|
The handler for the message is chosen using the following criteria:
|
|
|
|
-# If PostMessage() or the BMessenger is set to a specific handler, and
|
|
this handler is associated with this looper, than the message is
|
|
processed by that handler.
|
|
-# Else, the preferred handler is used. You can set this using
|
|
SetPreferredHandler().
|
|
-# If there is no preferred handler, then the looper itself will process
|
|
the message.
|
|
|
|
Because a looper usually is used in multiple threads, you should make sure
|
|
you Lock() and Unlock() it during most operations. Locking calls can be
|
|
recursive (so multiple locks can come from a single thread), but make sure
|
|
you pair every Lock() with an Unlock() call. Failing to do so will
|
|
inevitably cause a deadlock.
|
|
|
|
Because a looper provides a separate thread, and the inherited handler is
|
|
usually a default handler, you will most often use this class by
|
|
subclassing it. For example, you are likely to subclass BWindow (which is
|
|
derived from BLooper) to customize your window and handle the messages
|
|
sent to that window. You can override Run() in case you want to perform
|
|
additional tasks before (or right after) starting the message loop. You can
|
|
override QuitRequested() if you want to decline quitting in certain
|
|
circumstances. You can override Quit() in case you want to perform
|
|
additional procedures during closing time. You can also override
|
|
DispatchMessage() if you want to do something with all incoming messages
|
|
before they are dispatched to a handler.
|
|
|
|
BLooper is one of the major base classes of the Haiku application
|
|
programmers interface. Closely related classes are BMessage, BHandler and
|
|
BMessenger. It is used in the interface kit, for example by the BWindow
|
|
class, which makes sure every window runs it its own thread.
|
|
|
|
BLooper is a part of the chain in the eloquent messaging structure. For a
|
|
proper understanding of all its facets, have a look at the \ref app_messaging
|
|
"messaging overview".
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLooper::BLooper(const char* name, int32 priority, int32 portCapacity)
|
|
\brief Construct a new BLooper with a \a priority and an \a capacity.
|
|
|
|
The new looper is, by default, not running yet. If you have set up
|
|
everything properly, you may call Run().
|
|
|
|
\attention Remember that loopers should be created on the heap, because
|
|
they will \c delete themselves in the Quit() method.
|
|
|
|
\param name The name of the looper.
|
|
\param priority The priority of the message thread of this looper. The
|
|
default priority should be good enough for most tasks. Also, some
|
|
derived versions of BLooper will use a specialized priority. So it
|
|
is advised to leave this setting at the default, unless you know
|
|
why you would like another setting.
|
|
\param portCapacity Loopers use ports to send and receive messages (see
|
|
the kernel kit). Ports have a maximum capacity; if there are so many
|
|
messages queued that the port is full, all other incoming messages
|
|
are dropped. There are situations where the size of the port should
|
|
be different from the default. This might be when your looper
|
|
receives a lot of messages, or if the message handling thread runs
|
|
at a lower priority than normal, which would decrease the processing
|
|
speed. Finding a suitable value for these custom scenarios would be
|
|
done by testing.
|
|
|
|
\see Run()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLooper::~BLooper()
|
|
\brief Destruct the looper.
|
|
|
|
You will never delete a looper yourself. You should pass a
|
|
\c B_QUIT_REQUESTED message, or if you are destroying the looper from
|
|
inside its own message handling thread, you should call Quit().
|
|
|
|
\see Quit()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
///// Archiving /////
|
|
|
|
|
|
/*!
|
|
\name Archiving
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BLooper::BLooper(BMessage* data)
|
|
\brief Construct a looper from an archived message.
|
|
|
|
The \a data message has to be constructed by a BLooper::Archive() call.
|
|
Note that the data that is restored, is merely the port capacity and the
|
|
name of the looper/handler. Other data, such as filters, is not archived by
|
|
the default archiver.
|
|
|
|
\warning This constructor does no type check whatsoever. Since you can pass
|
|
any BMessage, you should - if you are not sure about the exact
|
|
type - use the Instantiate() method, which does check the type.
|
|
|
|
\see Instantiate()
|
|
\see Archive()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BArchivable* BLooper::Instantiate(BMessage* data)
|
|
\brief Static method to instantiate a looper from an archived message.
|
|
|
|
\return A pointer to the instantiated looper, or \c NULL if the \a data
|
|
is not a valid archived BLooper object.
|
|
|
|
\see BLooper(BMessage* data)
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::Archive(BMessage* data, bool deep) const
|
|
\brief Archive a looper to a message
|
|
|
|
Currently, only the name and the port capacity are archived. Any other
|
|
data, such as the filters, is not stored.
|
|
|
|
\param data The message to archive the object in.
|
|
\param deep This parameter is ignored, as BLooper does not have children.
|
|
|
|
\retval B_OK Archiving succeeded.
|
|
\retval B_BAD_VALUE The \a data parameter is not a valid message.
|
|
|
|
\see BLooper::Instantiate(BMessage* data)
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Message Mechanics
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::PostMessage(uint32 command)
|
|
\brief Post a message with the \a command as \c what identifier to this
|
|
looper.
|
|
|
|
Posting a message puts it in the message queue. The message passes through
|
|
the default handler chain.
|
|
|
|
\param command The \c what identifier of the message that needs to be sent.
|
|
|
|
\return A status code.
|
|
\retval B_OK The operation succeeded, and the message is sent to the port.
|
|
\retval B_ERROR There was a general operation error.
|
|
\retval B_BAD_VALUE This looper is not yet running and therefore cannot
|
|
receive messages.
|
|
|
|
\see PostMessage(BMessage *) if you want to send a message with data
|
|
members.
|
|
\see PostMessage(uint32, BHandler *, BHandler *) if you want to send a
|
|
message to a specific handler, and request a reply.
|
|
\see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing,
|
|
but with a complete message.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::PostMessage(BMessage* message)
|
|
\brief Post a \a message to this looper.
|
|
|
|
Posting a message puts it in the message queue. The message passes through
|
|
the default handler chain.
|
|
|
|
The \a message is copied, and as such, you should make sure you will not
|
|
leak it. The best way to send messages is like this:
|
|
\code
|
|
BMessage message;
|
|
message.what = B_DO_SOMETHING;
|
|
message.AddString("some_data", "This is data")
|
|
|
|
aLooper->PostMessage(&message);
|
|
\endcode
|
|
|
|
\param message The message you would like to pass to this method.
|
|
|
|
\return A status code.
|
|
\retval B_OK The operation succeeded, and the message is sent to the port.
|
|
\retval B_ERROR There was a general operation error.
|
|
\retval B_BAD_VALUE This looper is not yet running and therefore cannot
|
|
receive messages.
|
|
|
|
\see PostMessage(uint32) if you want to send a message without data
|
|
members.
|
|
\see PostMessage(uint32, BHandler *, BHandler *) if you want to send a
|
|
message to a specific handler, and request a reply.
|
|
\see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing,
|
|
but with a complete message.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::PostMessage(uint32 command, BHandler* handler,
|
|
BHandler* replyTo)
|
|
\brief Send a message with the \a command as \c what identifier to the
|
|
\a handler associated with this looper, and (optionally) request a
|
|
reply.
|
|
|
|
The target \a handler should be associated with this looper. This method
|
|
bypasses the default message queue.
|
|
|
|
\param command The value you want as the message's \c what identifier.
|
|
\param handler The handler you would like to pass this message to.
|
|
\param replyTo If you would like to request a reply, pass the handler to
|
|
which this reply should be directed to. If you pass \c NULL, you
|
|
will not receive a reply.
|
|
|
|
\return A status code.
|
|
\retval B_OK The operation succeeded, and the message is sent to the port.
|
|
\retval B_ERROR There was a general operation error.
|
|
\retval B_BAD_VALUE This looper is not yet running and therefore cannot
|
|
receive messages.
|
|
\retval B_MISMATCHED_VALUES The \a handler is not associated with this
|
|
looper.
|
|
|
|
\see PostMessage(uint32) if you want to send a message without data
|
|
members.
|
|
\see PostMessage(BMessage *) if you want to send a message with data
|
|
members.
|
|
\see PostMessage(BMessage *, BHandler *, BHandler *) if you want to send a
|
|
message to a specific handler, and request a reply.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::PostMessage(BMessage* message, BHandler* handler,
|
|
BHandler* replyTo)
|
|
\brief Send a \a message to the \a handler associated with this looper,
|
|
and (optionally) request a reply.
|
|
|
|
The target \a handler should be associated with this looper. This method
|
|
bypasses the default message queue.
|
|
|
|
The \a message is copied, and as such, you should make sure you will not
|
|
leak it. The best way to send messages is like this:
|
|
\code
|
|
BMessage message;
|
|
message.what = B_DO_SOMETHING;
|
|
message.AddString("some_data", "This is data")
|
|
|
|
aLooper->PostMessage(&message, aHandler);
|
|
\endcode
|
|
|
|
\param message The message you want to pass.
|
|
\param handler The handler you would like to pass this message to.
|
|
\param replyTo If you would like to request a reply, pass the handler to
|
|
which this reply should be directed to. If you pass \c NULL, you
|
|
will not receive a reply.
|
|
|
|
\return A status code.
|
|
\retval B_OK The operation succeeded, and the message is sent to the port.
|
|
\retval B_ERROR There was a general operation error.
|
|
\retval B_BAD_VALUE This looper is not yet running and therefore cannot
|
|
receive messages.
|
|
\retval B_MISMATCHED_VALUES The \a handler is not associated with this
|
|
looper.
|
|
|
|
\see PostMessage(uint32) if you want to send a message without data
|
|
members.
|
|
\see PostMessage(BMessage *) if you want to send a message with data
|
|
members.
|
|
\see PostMessage(uint32, BHandler *, BHandler *) if you want to send a
|
|
message without data to a specific handler, and request a reply.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Message Processing
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::DispatchMessage(BMessage *message, BHandler *handler)
|
|
\brief Dispatch a message to a handler. Override if there are messages that
|
|
you want to catch before they are sent to the handlers.
|
|
|
|
This method is called by the message looping thread to dispatch a message
|
|
to \a handler. If you implement the BLooper class and your looper receives
|
|
messages that absolutely have to be processed by the looper instead of any
|
|
of the handlers, override this method. For example, the default
|
|
implementation catches B_QUIT_REQUESTED messages before they are sent to
|
|
the handlers, so that the looper will quit at those messages.
|
|
|
|
You are discouraged from using this method to filter out any messages you
|
|
do not want to process. For this, there is a more generic method using
|
|
the BMessageFilter class. If you want to skip messages with certain
|
|
patterns, have a look at the AddCommonFilter() and SetCommonFilterList()
|
|
methods.
|
|
|
|
If you do override this method, please remember to call the
|
|
DispatchMessage() method of the parent class.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::MessageReceived(BMessage* message)
|
|
\brief Process a message received by the internal handler of this looper.
|
|
|
|
Reimplemented from BHandler::MessageReceived();
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessage* BLooper::CurrentMessage() const
|
|
\brief Retrieve the current message.
|
|
|
|
\attention Only call this method from within the thread that processes the
|
|
messages. It contains a pointer to the message that is currently
|
|
being handled. Due to the multithreaded nature of the operating
|
|
system, this method will not safely let you read the message
|
|
that is being processed by this handler from outside the context
|
|
of the processing. If you do want to use a message outside of
|
|
the processing thread, have a look at DetachCurrentMessage() to
|
|
safely retrieve a message.
|
|
|
|
\return A pointer to the message that is currently being processed. Note
|
|
that calling it from outside the thread that processes the message,
|
|
could give you a \c NULL pointer or an invalid pointer.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessage* BLooper::DetachCurrentMessage()
|
|
\brief Get ownership of the message currently being processed.
|
|
|
|
Retrieve the current message and gain ownership of it. This means that the
|
|
message will not be deleted as soon as the looper is done processing it.
|
|
You can then use it for different purposes.
|
|
|
|
\attention Only call this method from within the thread that processes the
|
|
messages. Due to the multithreaded nature of the operating
|
|
system, calling it from another thread is very likely to give
|
|
you an invalid or a \c NULL pointer.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessageQueue* BLooper::MessageQueue() const
|
|
\brief Get a pointer to the internal message queue of this looper.
|
|
|
|
You can use this pointer to manipulate the message queue. Note that the
|
|
message that is being processed is already detached from this queue.
|
|
|
|
\return A pointer to the internal message queue.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::IsMessageWaiting() const
|
|
\brief Check if there is a message waiting.
|
|
|
|
\return \c true if there are still messages to be processed,
|
|
\c false if there is no message waiting.
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Handler Management
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::AddHandler(BHandler* handler)
|
|
\brief Associate a \a handler to this looper.
|
|
|
|
The \a handler will be associated to this looper. By default, the handler
|
|
in this looper will be chained to the supplied \a handler.
|
|
|
|
\param handler The handler to associate with this looper. If the handler
|
|
is already associated to another looper, the operation will fail
|
|
silently. Check beforehand if you cannot be sure that the
|
|
\a handler is unassociated.
|
|
|
|
\see RemoveHandler()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::RemoveHandler(BHandler* handler)
|
|
\brief Disassociate a \a handler from this looper.
|
|
|
|
If the handler is disassociated, it can be reassociated to another looper.
|
|
|
|
\return \c true if the \a handler has been removed from this looper,
|
|
\c false The \a handler was invalid or the handler was not
|
|
associated to this looper.
|
|
|
|
\see AddHandler()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BLooper::CountHandlers() const
|
|
\brief Get the number of handlers associated with this looper.
|
|
|
|
\see HandlerAt()
|
|
\see IndexOf()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHandler* BLooper::HandlerAt(int32 index) const
|
|
\brief Get the handler at an \a index of the list of associated handlers.
|
|
|
|
\return A pointer to the handler at that \a index, or \c NULL if the
|
|
\a index is out of range.
|
|
|
|
\see CountHandlers()
|
|
\see IndexOf()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BLooper::IndexOf(BHandler* handler) const
|
|
\brief Get the index of the \a handler that is in the associated handler
|
|
list.
|
|
|
|
\return The index of the handler in the list if the \a handler is in the
|
|
list, else this method will return -1.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHandler* BLooper::PreferredHandler() const
|
|
\brief Get the preferred handler.
|
|
|
|
\return A pointer to the preferred handler, or \c NULL if none is set.
|
|
|
|
\see SetPreferredHandler()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::SetPreferredHandler(BHandler* handler)
|
|
\brief Set a preferred handler.
|
|
|
|
If messages are posted to this looper using one of the PostMessage()
|
|
methods without a specific BHandler argument, the messages will be handled
|
|
by the looper itself (since a looper is a subclass of BHandler, this is
|
|
perfectly possible). If you want to override that behavior, you should set
|
|
a preferred handler. This handler will be called if incoming messages do
|
|
not ask to be directly passed on to a specific handler.
|
|
|
|
\param handler The preferred handler you want undesignated messages to be
|
|
handled by. If you want to unset the preferred handler, pass
|
|
\c NULL. If the supplied \a handler is not associated with this
|
|
looper, this call will fail silently and the current preferred
|
|
handler will be unset.
|
|
|
|
\see PreferredHandler()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Loop Control
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn thread_id BLooper::Run()
|
|
\brief Start the event loop.
|
|
|
|
After the looper has been constructed, it needs to be started using this
|
|
method. A thread will be spawned, which will receive messages.
|
|
|
|
Make sure the looper is not yet running before you call this method.
|
|
|
|
\return A (positive) thread id if spawning the thread succeeded, or an
|
|
error code.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::Quit()
|
|
\brief Hook method that is called after a \c B_QUIT_REQUESTED message.
|
|
|
|
If you want to quit and delete the looper, you should post a
|
|
\c B_QUIT_REQUESTED message. This will first call the hook method
|
|
QuitRequested(), which can be overridden in child classes in case there
|
|
are conditions that would prevent the looper to be quit. If you really
|
|
know what you are doing, and you definitely want to quit this looper,
|
|
you may call this method, but only after performing a Lock() operation.
|
|
|
|
Override this method if your subclass needs to perform specific clean-up
|
|
tasks. Remember to call the base class implementation when you're done.
|
|
|
|
\attention You will not have to delete the looper object, if a looper quits
|
|
it will delete itself.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::QuitRequested()
|
|
\brief Hook method that is called during a \c B_QUIT_REQUESTED message.
|
|
|
|
This hook function is called by the looper thread when a
|
|
\c B_QUIT_REQUESTED is received. The default implementation always accepts
|
|
the message, but if your subclass needs a special condition to be met
|
|
before actually accepting a quit message, you can test for that condition
|
|
in this hook method. A good example is a window (which is a derivative of
|
|
BLooper), which contains a modified document. The condition may be that a
|
|
modal dialog requesting a path of action is closed.
|
|
|
|
\return \c true if the looper can be quit and destroyed,
|
|
\c false if this method does not accept the quit message
|
|
and continue processing messages.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::Lock()
|
|
\brief Lock the looper.
|
|
|
|
For most operations involving the internal data of the looper, you need to
|
|
hold the lock. Each looper implements a global lock, which you can use to
|
|
perform operations on internal data in a thread-safe manner.
|
|
|
|
Do not forget to pair each Lock() request with an Unlock() request. Lock()
|
|
requests can be stacked, which means that recursively locking a looper from
|
|
a thread that actually holds the lock, will not cause a deadlock. See
|
|
BLocker for more information on locking internals.
|
|
|
|
\return \c true if the locking request succeeded,
|
|
\c false if the locking request could not be completed. There are a
|
|
variety of reasons for this to happen, for example when the
|
|
looper is destroyed.
|
|
|
|
\see Unlock()
|
|
\see LockWithTimeout()
|
|
\see IsLocked()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::Unlock()
|
|
\brief Unlock a locked looper.
|
|
|
|
Use this method paired with Lock() calls, to release a lock. Make sure that
|
|
this method is only called on a locked looper.
|
|
|
|
\see Lock()
|
|
\see LockWithTimeout()
|
|
\see IsLocked()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::IsLocked() const
|
|
\brief Check if a looper is locked.
|
|
|
|
\return \c true if the looper is locked,
|
|
\c false if the looper is not locked, or the looper has been
|
|
deleted.
|
|
|
|
\see Lock()
|
|
\see Unlock()
|
|
\see LockWithTimeout()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::LockWithTimeout(bigtime_t timeout)
|
|
\brief Lock a looper with a \a timeout.
|
|
|
|
This method locks the looper like Lock(), but if the locking request does
|
|
not succeed within the provided \a timeout, the method will return.
|
|
|
|
\param timeout The maximum time to wait for the lock request to succeed.
|
|
|
|
\return A status code.
|
|
\retval B_OK The lock is acquired.
|
|
\retval B_BAD_VALUE The looper has been destroyed.
|
|
\retval "other errors" There was an error acquiring the lock.
|
|
|
|
\see Lock()
|
|
\see Unlock()
|
|
\see IsLocked()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn thread_id BLooper::Thread() const
|
|
\brief Return the thread id of the internal message looper thread.
|
|
|
|
If the looper is not yet running, this method will return 0.
|
|
|
|
\see Run()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn team_id BLooper::Team() const
|
|
\brief Return the team id in which this looper exists.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BLooper* BLooper::LooperForThread(thread_id thread)
|
|
\brief Static method to retrieve a BLooper for a specified \a thread.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Loop Debugging
|
|
|
|
These methods may aid you in debugging problems when they occur, but do not
|
|
use these in actual production code. These methods are unreliable because
|
|
they are not thread-safe, and as such are only useful in specific debugging
|
|
situations. Handle with care.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn thread_id BLooper::LockingThread() const
|
|
\brief Return the thread id of the thread that currently holds the lock.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BLooper::CountLocks() const
|
|
\brief Return the number of recursive locks that are currently being held
|
|
on this looper.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BLooper::CountLockRequests() const
|
|
\brief Return the number of pending locks.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn sem_id BLooper::Sem() const
|
|
\brief Return the id of the semaphore that is used to lock this looper.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Scripting
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BHandler* BLooper::ResolveSpecifier(BMessage* message, int32 index,
|
|
BMessage* specifier, int32 what, const char* property)
|
|
\brief Determine the proper handler for a scripting message.
|
|
|
|
\copydetails BHandler::ResolveSpecifier()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::GetSupportedSuites(BMessage* data)
|
|
\brief Reports the suites of messages and specifiers that derived classes
|
|
understand.
|
|
|
|
\copydetails BHandler::GetSupportedSuites()
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Looper Message Filters
|
|
|
|
Note that filters added with these methods will be applied to all
|
|
associated handlers. Have a look at the filtering methods of the BHandler
|
|
class to see how filters can be applied to the inherited handler of this
|
|
looper specifically.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::AddCommonFilter(BMessageFilter* filter)
|
|
\brief Add a common filter to the list of filters that are applied to all
|
|
incoming messages.
|
|
|
|
Filters can only be applied once, so they cannot be shared between loopers,
|
|
a handler and a looper or between two handlers.
|
|
|
|
The \a filter is not copied; rather a pointer is stored. Keep the \a filter
|
|
alive as long as it is used by a looper.
|
|
|
|
\see RemoveCommonFilter()
|
|
\see SetCommonFilterList()
|
|
\see CommonFilterList()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BLooper::RemoveCommonFilter(BMessageFilter* filter)
|
|
\brief Remove a \a filter from the common message filter list.
|
|
|
|
Note that this will not free the memory used by the \a filter, so you
|
|
should dispose of it yourself.
|
|
|
|
\see AddCommonFilter()
|
|
\see SetCommonFilterList()
|
|
\see CommonFilterList()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BLooper::SetCommonFilterList(BList* filters)
|
|
\brief Set a new list of \a filters that need to be applied to all
|
|
incoming messages.
|
|
|
|
You are responsible for validating that all the items in the list of
|
|
\a filters are actual filters. The old list is discarded; all the filters
|
|
are \b destroyed.
|
|
|
|
Note that filters can only be applied to one looper or handler. If any
|
|
of the filters is already associated with another one, this call will fail.
|
|
|
|
\see AddCommonFilter()
|
|
\see RemoveCommonFilter()
|
|
\see CommonFilterList()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BList* BLooper::CommonFilterList() const
|
|
\brief Return a list of filters applied to all incoming messages.
|
|
|
|
\return A pointer to the internal filter list, or \c NULL if such a list
|
|
has not yet been created. Please note that you should use the
|
|
internal list management functions to manipulate the internal
|
|
filter list, in order to maintain internal consistency.
|
|
|
|
\see AddCommonFilter()
|
|
\see RemoveCommonFilter()
|
|
\see SetCommonFilterList()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\fn status_t BLooper::Perform(perform_code d, void* arg)
|
|
\brief Internal method.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BMessage* BLooper::MessageFromPort(bigtime_t timeout)
|
|
\brief Hook method to retrieve a message from the looper's port.
|
|
|
|
The default implementation is called by the internal message looping thread
|
|
and retrieves the next message from the port that belongs to this looper.
|
|
|
|
If you use a looper in a context where it might receive messages from other
|
|
sources, you can override this method in order to insert these methods into
|
|
the message processing. Note that any messages that are returned by this
|
|
method will be deleted by this looper, so make sure you have ownership of
|
|
the message. If you override this method, remember to call the base
|
|
implementation every now and then, in order to retrieve the messages
|
|
arriving at the default port.
|
|
|
|
\since Haiku R1
|
|
*/
|