diff --git a/docs/user/app/_app_intro.dox b/docs/user/app/_app_intro.dox index 4000a94cd1..c2b484e093 100644 --- a/docs/user/app/_app_intro.dox +++ b/docs/user/app/_app_intro.dox @@ -17,15 +17,16 @@ documents referenced before going to any other part of the API. We can divide the classes in the application kit up in two categories. The - biggest part of the classes are in the 'messaging' classes. The following - are part of it: + biggest part of the classes are in the 'messaging' classes. Have a look at + the \link app_messaging Introduction to Messaging \endlink for more + information. The following classes are part of it: - BHandler - BInvoker - BLooper - BMessage - BMessageFilter - BMessageQueue - - BMessageRUnner + - BMessageRunner - BMessenger The second category is the 'system interaction' category. These classes diff --git a/docs/user/app/_app_messaging.dox b/docs/user/app/_app_messaging.dox new file mode 100644 index 0000000000..c7e1199d48 --- /dev/null +++ b/docs/user/app/_app_messaging.dox @@ -0,0 +1,152 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + */ + + +/*! + \page app_messaging Messaging Foundations + + One of the foundations of the Haiku API is the messaging system. This + framework is the basis for the efficient multithreaded Haiku applications, + because it solves one of the fundamental issues of multithreading: it + allows you to easily and securely communicate between threads. But the + framework goes even further: it allows inter-application communication! + + This page will introduce you to the subject of messaging. It is meant as a + broad overview to the classes, rather than a tutorial. If you are looking + for effective messaging techniques or a tutorial on messaging, have a look + at the developer section of the Haiku website. + + Table of contents + - Overview of the Messaging Classes + - Receiving and Handling Messages + - Sending messages + + \section app_messaging_overview Overview of the Messaging Classes + + \subsection app_messaging_overview_bmessage BMessage + + The BMessage class is the class that is in the center of all the messenger + operations, because it represents a message. A message is nothing more than + an object that contains: + - The \c what member, an \c uint32 that determines the type of message. + Some constants are defined by the Haiku API, for example B_MOUSE_DOWN or + B_QUIT_REQUESTED. + - Zero or more data objects. BMessage is a powerful data container that + keeps track of different sorts of data. BMessage provides many convenient + Add*() methods, for example BMessage::AddBool(). With the corresponding + Find*() method (in this example, FindBook()) you can retrieve the data. + + BMessage itself is generic, its syntax and semantics are determined by the + context. The Haiku API defines several messages and their required data + members. Several applications provide a scripting interface with defined + message syntax. You can do the same for your application. + + \subsection app_messaging_overview_blooper BLooper + + Objects of the BLooper type are objects that run message loops. Every + object runs in its own thread. The BLooper objects continually check for + incoming messages, and they try to find a BHandler to actually handle the + messages within their thread context. Message handling within a thread is + synchronous. + + BLooper inherits BHandler, the base class for message handling. However, it + is possible to chain additional handlers to the object. For example, if you + have an application that understands different networking protocols, and + you support extensions that understand the base protocol, these extensions + can provide handlers that you can chain in your general message parser + thread. See AddHandler() and SetPreferredHandler() for information on + handlers. + + Messages can be posted to the looper by using the object's PostMessage() + method. This method puts the message in the BMessageQueue of the looper. + Since PostMessage() is asynchronous, the message might not be handled + immediately. See \link app_messaging_overview_bmessenger BMessenger + \endlink for a synchronous implementation. + + Loopers can have a generic filter that discards messages based on + user-definable characteristics. The BMessageFilter class provides the + foundation for the qualifying of messages. See AddCommonFilterList() and + SetCommonFilterList() for more information. + + To get the most out of the functionality of BLooper, it is usually + subclassed to create a self-contained event 'machine'. Most of the time, + these subclasses also perform the message handling, which is possible + due to the fact that it is also a subclass of BHandler. + + In the Haiku API, there are two major classes that inherit BLooper: + the base application class, BApplication, and the window class, BWindow. + Because they inherit BLooper, each application and each window has its + own message loop. This makes every window quick and responsive. To keep + your applications running smoothly, it is advisable to make sure that + event handling that requires more processing power, is done within its own + BLooper context. Networking usually qualifies as a candidate for its own + thread. + + \section app_messaging_overview_bhandler BHandler + + Objects of the BHandler type are associated to BLoopers. When they are + created, they should be passed to the BLooper::AddHandler() method of the + looper they want to handle messages for. They can then either be set as + preferred handlers (by chaining them with BLooper::SetPreferredHandler()), + or they can be added to other BHandlers with the SetNextHandler() method. + + The magic of the class happens in the MessageReceived() method. In your + subclasses you override this method, to check the incoming BMessage. + Usually, you check the \c what member of the message in a switch statement. + If your handler cannot handle the object, it will pass the message on to + the parent class. + + \warning Don't forget to actuall call + baseclass::MessageReceived(). Failing to do this will mean + that the message chain will not completely be followed, which can lead + to unhandled messages. There might be some internal system messages + that the Haiku API classes handle, and not actually handling these + messages could lead to inconsistent internal behavior. + + \section app_messaging-overview-bmessenger BMessenger + + BMessenger objects can send messages to both local and remote targets. For + local targets, a BMessenger provides an advantage over directly calling + the BLooper::PostMessage() method: some variants of the + BMessenger::SendMessage() methods allow for synchronous replies. So, the + call will actually verify the handling thread processes the message, and + reply to the sender. + + The other feature of BMessenger is that it is able to be constructed with + the signature of another application as argument. This allows the messenger + to pass messages to other applications. It facilitates inter-application + communication. + + \section app_messaging-overview-other Other messaging classes + + There are several convenience classes supplied with the application kit, + which can make your life easier in some specific cases. + + * BInvoker binds together a message and a target. By calling + BInvoker::Invoke(), the message will be sent. This class is inherited by + the controls in the interface kit, such as BButton. + * A BMessageRunner object will send messages to a specified target with + specified intervals in between. + * BMessageQueue is a class that is also internally used by BLooper. It + provides a queue of messages, with convenience functions of managing + this queue. + * BMessageFilter is the base class of the filters. Filters can be applied + to BLoopers to filter all incoming messages, or to BHandlers to filter + messages that could be handled by that object. The filter object can be + subclassed and extended by overriding the Filter() method. + + \section app-messaging-receiving Receiving Messages + + To do... + + \section app-messaging-sending Sending Messages + + To do... + +*/ + \ No newline at end of file