docs/user/app/_app_messaging.dox

   1 /*
   2  * Copyright 2007 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  */
   8
   9 /*!
  10         \page app_messaging Messaging Foundations
  11
  12         One of the foundations of the Haiku API is the messaging system. This
  13         framework is the basis for the efficient multithreaded Haiku applications,
  14         because it solves one of the fundamental issues of multithreading: it
  15         allows you to easily and securely communicate between threads. The
  16         framework allows inter-application messaging as well as
  17         intra-application messaging, and it will always use the most effective
  18         mechanism for the communication automatically.
  19
  20         This page will introduce you to the subject of messaging. It is meant as a
  21         broad overview to the classes, rather than a tutorial. If you are looking
  22         for effective messaging techniques or a tutorial on messaging, have a look
  23         at the developer section of the Haiku website.
  24
  25         <b>Table of contents</b>
  26         - Overview of the Messaging Classes
  27         - Receiving and Handling Messages
  28         - Sending messages
  29
  30         \section app_messaging_overview Overview of the Messaging Classes
  31
  32         \subsection app_messaging_overview_bmessage BMessage
  33
  34         The BMessage class is the class that is in the center of all the messenger
  35         operations, because it represents a message. A message is nothing more than
  36         an object that contains:
  37         - The \c what member, an \c uint32 that determines the type of message.
  38           Some constants are defined by the Haiku API, for example B_MOUSE_DOWN or
  39           B_QUIT_REQUESTED.
  40         - Zero or more data objects. BMessage is a powerful data container that
  41           keeps track of different sorts of data. BMessage provides many convenient
  42           Add*() methods, for example BMessage::AddBool(). With the corresponding
  43           Find*() method (in this example,
  44           \link BMessage::FindBool(const char *, int32, bool *) const FindBool() \endlink)
  45           you can retrieve the data.
  46
  47         BMessage itself is generic, its syntax and semantics are determined by the
  48         context. The Haiku API defines several messages and their required data
  49         members. Several applications provide a scripting interface with defined
  50         message syntax. You can do the same for your application.
  51
  52         \subsection app_messaging_overview_blooper BLooper
  53
  54         Objects of the BLooper type are objects that run message loops. Every
  55         object runs in its own thread. The BLooper objects continually check for
  56         incoming messages. To process the messages, the looper looks for message
  57         handlers that handle the messages within the thread's context. Message
  58         handling within a looper is synchronous.
  59
  60         BLooper inherits BHandler, the base class for message handling. However, it
  61         is possible to chain additional handlers to the object. For example, if you
  62         have an application that understands different networking protocols, and
  63         you support extensions that understand the base protocol, these extensions
  64         can provide handlers that you can chain in your general message parser
  65         thread. See AddHandler() and SetPreferredHandler() for information on
  66         handlers.
  67
  68         Messages can be posted to the looper by using the object's PostMessage()
  69         method. This method puts the message in the BMessageQueue of the looper.
  70         Since PostMessage() is asynchronous, the message might not be handled
  71         immediately. See \ref app_messaging_overview_bmessenger "BMessenger"
  72         for a synchronous implementation.
  73
  74         Loopers can have a generic filter that discards messages based on
  75         user-definable characteristics. The BMessageFilter class provides the
  76         foundation for the qualifying of messages. See AddCommonFilterList() and
  77         SetCommonFilterList() for more information.
  78
  79         To get the most out of the functionality of BLooper, it is usually
  80         subclassed to create a self-contained event 'machine'. Most of the time,
  81         these subclasses also perform the message handling, which is possible
  82         due to the fact that it is also a subclass of BHandler.
  83
  84         In the Haiku API, there are two major classes that inherit BLooper:
  85         the base application class, BApplication, and the window class, BWindow.
  86         Because they inherit BLooper, each application and each window has its
  87         own message loop. This makes every window quick and responsive. To keep
  88         your applications running smoothly, it is advisable to make sure that
  89         event handling that requires more processing power, is done within its own
  90         BLooper context. Networking usually qualifies as a candidate for its own
  91         thread.
  92
  93         \subsection app_messaging_overview_bhandler BHandler
  94
  95         Objects of the BHandler type are associated to BLoopers. When they are
  96         created, they should be passed to the BLooper::AddHandler() method of the
  97         looper they want to handle messages for. They can then either be set as
  98         preferred handlers (by chaining them with BLooper::SetPreferredHandler()),
  99         or they can be added to other BHandlers with the SetNextHandler() method.
 100
 101         The magic of the class happens in the MessageReceived() method. In your
 102         subclasses you override this method, to check the incoming BMessage.
 103         Usually, you check the \c what member of the message in a switch statement.
 104         If your handler cannot handle the object, it will pass the message on to
 105         the parent class.
 106
 107         \warning Don't forget to actuall call the MessageReceived() method of the
 108                 base class. Failing to do this will mean that the message chain will
 109                 not completely be followed, which can lead to unhandled messages. There
 110                 might be some internal system messages that the Haiku API classes
 111                 handle, and not actually handling these messages could lead to
 112                 inconsistent internal behavior.
 113
 114         \subsection app_messaging_overview_bmessenger BMessenger
 115
 116         BMessenger objects can send messages to both local and remote targets. For
 117         local targets, a BMessenger provides an advantage over directly calling
 118         the BLooper::PostMessage() method: some variants of the
 119         BMessenger::SendMessage() methods allow for synchronous replies. So, the
 120         call will actually verify the handling thread processes the message, and
 121         reply to the sender.
 122
 123         The other feature of BMessenger is that it is able to be constructed with
 124         the signature of another application as argument. This allows the messenger
 125         to pass messages to other applications. It facilitates inter-application
 126         communication.
 127
 128         \subsection app_messaging-overview-other Other messaging classes
 129
 130         There are several convenience classes supplied with the application kit,
 131         which can make your life easier in some specific cases.
 132
 133         - BInvoker binds together a message and a target. By calling
 134           BInvoker::Invoke(), the message will be sent. This class is inherited by
 135           the controls in the interface kit, such as BButton.
 136         - A BMessageRunner object will send messages to a specified target with
 137           specified intervals in between.
 138         - BMessageQueue is a class that is also internally used by BLooper. It
 139           provides a queue of messages, with convenience functions of managing
 140           this queue.
 141         - BMessageFilter is the base class of the filters. Filters can be applied
 142           to BLoopers to filter all incoming messages, or to BHandlers to filter
 143           messages that could be handled by that object. The filter object can be
 144           subclassed and extended by overriding the \link BMessageFilter::Filter()
 145           Filter() \endlink method.
 146
 147         \section app-messaging-receiving Receiving Messages
 148
 149         To do...
 150
 151         \section app-messaging-sending Sending Messages
 152
 153         To do...
 154 */