1# 2 3While the run loop provided by BTstack is sufficient for new designs, 4BTstack is often used with or added to existing projects. In this case, 5the run loop, data sources, and timers may need to be adapted. The 6following two sections provides a guideline for single and 7multi-threaded environments. 8 9To simplify the discussion, we’ll consider an application split into 10“Main ”, “Communication Logic”, and “BTstack”. The Communication Logic 11contains the packet handler (PH) that handles all asynchronous events 12and data packets from BTstack. The Main Application makes use of the 13Communication Logic for its Bluetooth communication. 14 15 16## Adapting BTstack for Single-Threaded Environments {#sec:singlethreadingIntegration} 17 18 19In a single-threaded environment, all application components run on the 20same (single) thread and use direct function calls as shown in 21Figure {@fig:BTstackSingle}. 22 23 {#fig:BTstackSingle} 24 25BTstack provides a basic run loop that supports the concept of data 26sources and timers, which can be registered centrally. This works well 27when working with a small MCU and without an operating system. To adapt 28to a basic operating system or a different scheduler, BTstack’s run loop 29can be implemented based on the functions and mechanism of the existing 30system. 31 32Currently, we have two examples for this: 33 34- *btstack_run_loop_posix.c* is an implementation for POSIX compliant 35 systems. The data sources are modeled as file descriptors and 36 managed in a linked list. Then, the *select* function is used to wait 37 for the next file descriptor to become ready or timer to expire. 38 39- *btstack_run_loop_cocoa.c* is an integration for the CoreFoundation 40 Framework used in OS X and iOS. All run loop functions are 41 implemented in terms of CoreFoundation calls, data sources and 42 timers are modeled as CFSockets and CFRunLoopTimer respectively. 43 44- *btstack_run_loop_windows* is an implementation for Windows environment. 45 The data sources are modeled with Event objects and managed in a linked list. 46 Then, the *WaitForMultipleObjects* is used to wait for the next Event to 47 becomre ready or timer to expire. 48 49- *btstack_run_loop_qt* is an integration for the Qt run loop. 50 The data sources on Windows systems use Event objects via Qt's QEventNotifier adapter, 51 while a QSocketNotifier is used for Mac/Linux to handle file descriptors. 52 With these in place, the Windows/POSIX implemenations for HCI USB/H2 and HCI H4 can be used. 53 54## Adapting BTstack for Multi-Threaded Environments {#sec:multithreadingIntegration} 55 56 57The basic execution model of BTstack is a general while loop. Aside from 58interrupt-driven UART and timers, everything happens in sequence. When 59using BTstack in a multi-threaded environment, this assumption has to 60stay valid - at least with respect to BTstack. For this, there are two 61common options: 62 63 64- The Communication Logic is implemented on a dedicated BTstack 65 thread, and the Main Application communicates with the BTstack 66 thread via application-specific messages over an Interprocess 67 Communication (IPC) as depicted in Figure {@fig:MTMonolithic}. 68 This option results in less code and quick adaption. 69 70  {#fig:MTMonolithic} 71 72- BTstack must be extended to run standalone, i.e, as a Daemon, on a 73 dedicated thread and the Main Application controls this daemon via 74 BTstack extended HCI command over IPC - this is used for the 75 non-embedded version of BTstack e.g., on the iPhone and it is depicted 76 in Figure {@fig:MTDaemon}. This option requires more code but provides 77 more flexibility. 78 79  {#fig:MTDaemon} 80
