diff options
Diffstat (limited to '')
-rw-r--r-- | third_party/libwebrtc/api/g3doc/index.md | 51 | ||||
-rw-r--r-- | third_party/libwebrtc/api/g3doc/threading_design.md | 74 |
2 files changed, 125 insertions, 0 deletions
diff --git a/third_party/libwebrtc/api/g3doc/index.md b/third_party/libwebrtc/api/g3doc/index.md new file mode 100644 index 0000000000..b576514d5e --- /dev/null +++ b/third_party/libwebrtc/api/g3doc/index.md @@ -0,0 +1,51 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *--> + +# The WebRTC API + +The public API of the WebRTC library consists of the api/ directory and +its subdirectories. No other files should be depended on by webrtc users. + +Before starting to code against the API, it is important to understand +some basic concepts, such as: + +* Memory management, including webrtc's reference counted objects +* [Thread management](threading_design.md) + +## Using WebRTC through the PeerConnection class + +The +[PeerConnectionInterface](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/peer_connection_interface.h?q=webrtc::PeerConnectionInterface) +class is the recommended way to use the WebRTC library. + +It is closely modeled after the Javascript API documented in the [WebRTC +specification](https://w3c.github.io/webrtc-pc/). + +PeerConnections are created using the [PeerConnectionFactoryInterface](https://source.chromium.org/search?q=webrtc::PeerConnectionFactoryInterface). + +There are two levels of customization available: + +* Pass a PeerConnectionFactoryDependencies object to the function that creates + a PeerConnectionFactory. This object defines factories for a lot of internal + objects inside the PeerConnection, so that users can override them. + All PeerConnections using this interface will have the same options. +* Pass a PeerConnectionInterface::RTCConfiguration object to the + CreatePeerConnectionOrError() function on the + PeerConnectionFactoryInterface. These customizations will apply only to a + single PeerConnection. + +Most functions on the PeerConnection interface are asynchronous, and take a +callback that is executed when the function is finished. The callbacks are +mostly called on the thread that is passed as the "signaling thread" field of +the PeerConnectionFactoryDependencies, or the thread that called +PeerConnectionFactory::CreatePeerConnectionOrError() if no thread is given. + +See each class' module documentation for details. + +## Using WebRTC components without the PeerConnection class + +This needs to be done carefully, and in consultation with the WebRTC team. There +are non-obvious dependencies between many of the components. + + + diff --git a/third_party/libwebrtc/api/g3doc/threading_design.md b/third_party/libwebrtc/api/g3doc/threading_design.md new file mode 100644 index 0000000000..8023b5eda0 --- /dev/null +++ b/third_party/libwebrtc/api/g3doc/threading_design.md @@ -0,0 +1,74 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *--> + +# API Threading Design considerations + +The header files in this directory form the API to the WebRTC library +that is intended for client applications' use. + +This API is designed to be used on top of a multithreaded runtime. + +The public API functions are designed to be called from a single thread* +(the "client thread"), and can do internal dispatching to the thread +where activity needs to happen. Those threads can be passed in by the +client, typically as arguments to factory constructors, or they can be +created by the library if factory constructors that don't take threads +are used. + +Many of the functions are designed to be used in an asynchronous manner, +where a function is called to initiate an activity, and a callback will +be called when the activity is completed, or a handler function will +be called on an observer object when interesting events happen. + +Note: Often, even functions that look like simple functions (such as +information query functions) will need to jump between threads to perform +their function - which means that things may happen on other threads +between calls; writing "increment(x); increment(x)" is not a safe +way to increment X by exactly two, since the increment function may have +jumped to another thread that already had a queue of things to handle, +causing large amounts of other activity to have intervened between +the two calls. + +(*) The term "thread" is used here to denote any construct that guarantees +sequential execution - other names for such constructs are task runners +and sequenced task queues. + +## Client threads and callbacks + +At the moment, the API does not give any guarantee on which thread* the +callbacks and events are called on. So it's best to write all callback +and event handlers like this (pseudocode): +``` +void ObserverClass::Handler(event) { + if (!called_on_client_thread()) { + dispatch_to_client_thread(bind(handler(event))); + return; + } + // Process event, we're now on the right thread +} +``` +In the future, the implementation may change to always call the callbacks +and event handlers on the client thread. + +## Implementation considerations + +The C++ classes that are part of the public API are also used to derive +classes that form part of the implementation. + +This should not directly concern users of the API, but may matter if one +wants to look at how the WebRTC library is implemented, or for legacy code +that directly accesses internal APIs. + +Many APIs are defined in terms of a "proxy object", which will do a blocking +dispatch of the function to another thread, and an "implementation object" +which will do the actual +work, but can only be created, invoked and destroyed on its "home thread". + +Usually, the classes are named "xxxInterface" (in api/), "xxxProxy" and +"xxx" (not in api/). WebRTC users should only need to depend on the files +in api/. In many cases, the "xxxProxy" and "xxx" classes are subclasses +of "xxxInterface", but this property is an implementation feature only, +and should not be relied upon. + +The threading properties of these internal APIs are NOT documented in +this note, and need to be understood by inspecting those classes. |