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