1# Design considerations 2 3The header files in this directory form the API to the WebRTC library 4that is intended for client applications' use. 5 6This API is designed to be used on top of a multithreaded runtime. 7 8The public API functions are designed to be called from a single thread* 9(the "client thread"), and can do internal dispatching to the thread 10where activity needs to happen. Those threads can be passed in by the 11client, typically as arguments to factory constructors, or they can be 12created by the library if factory constructors that don't take threads 13are used. 14 15Many of the functions are designed to be used in an asynchronous manner, 16where a function is called to initiate an activity, and a callback will 17be called when the activity is completed, or a handler function will 18be called on an observer object when interesting events happen. 19 20Note: Often, even functions that look like simple functions (such as 21information query functions) will need to jump between threads to perform 22their function - which means that things may happen on other threads 23between calls; writing "increment(x); increment(x)" is not a safe 24way to increment X by exactly two, since the increment function may have 25jumped to another thread that already had a queue of things to handle, 26causing large amounts of other activity to have intervened between 27the two calls. 28 29(*) The term "thread" is used here to denote any construct that guarantees 30sequential execution - other names for such constructs are task runners 31and sequenced task queues. 32 33# Client threads and callbacks 34 35At the moment, the API does not give any guarantee on which thread* the 36callbacks and events are called on. So it's best to write all callback 37and event handlers like this (pseudocode): 38<pre> 39void ObserverClass::Handler(event) { 40 if (!called_on_client_thread()) { 41 dispatch_to_client_thread(bind(handler(event))); 42 return; 43 } 44 // Process event, we're now on the right thread 45} 46</pre> 47In the future, the implementation may change to always call the callbacks 48and event handlers on the client thread. 49 50# Implementation considerations 51 52The C++ classes that are part of the public API are also used to derive 53classes that form part of the implementation. 54 55This should not directly concern users of the API, but may matter if one 56wants to look at how the WebRTC library is implemented, or for legacy code 57that directly accesses internal APIs. 58 59Many APIs are defined in terms of a "proxy object", which will do a blocking 60dispatch of the function to another thread, and an "implementation object" 61which will do the actual 62work, but can only be created, invoked and destroyed on its "home thread". 63 64Usually, the classes are named "xxxInterface" (in api/), "xxxProxy" and 65"xxx" (not in api/). WebRTC users should only need to depend on the files 66in api/. In many cases, the "xxxProxy" and "xxx" classes are subclasses 67of "xxxInterface", but this property is an implementation feature only, 68and should not be relied upon. 69 70The threading properties of these internal APIs are NOT documented in 71this note, and need to be understood by inspecting those classes. 72