nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 1 | # QUIC platform API |
| 2 | |
| 3 | This directory contains the infrastructure blocks needed to support QUIC in |
| 4 | certain platform. These APIs act as interaction layers between QUIC core and |
| 5 | either the upper layer application (i.e. Chrome, Envoy) or the platform's own |
| 6 | infrastructure (i.e. logging, test framework and system IO). QUIC core needs the |
| 7 | implementations of these APIs to build and function appropriately. There is |
| 8 | unidirectional dependency from QUIC core to most of the APIs here, such as |
| 9 | QUIC_LOG and QuicMutex, but a few APIs also depend back on QUIC core's basic |
| 10 | QUIC data types, such as QuicClock and QuicSleep. |
| 11 | |
| 12 | - APIs used by QUIC core: |
| 13 | |
| 14 | Most APIs are used by QUIC core to interact with platform infrastructure |
| 15 | (i.e. QUIC_LOG) or to wrap around platform dependent data types (i.e. |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 16 | QuicThread), the dependency is: |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 17 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 18 | ``` |
| 19 | application -> quic_core -> quic_platform_api |
| 20 | | | |
| 21 | v v |
| 22 | platform_infrastructure <- quic_platform_impl |
| 23 | ``` |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 24 | |
| 25 | - APIs used by applications: |
| 26 | |
| 27 | Some APIs are used by applications to interact with QUIC core (i.e. |
| 28 | QuicMemSlice). For such APIs, their dependency model is: |
| 29 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 30 | ``` |
| 31 | application -> quic_core -> quic_platform_api |
| 32 | | ^ |
| 33 | | | |
| 34 | -------------------> quic_platform_impl |
| 35 | | | |
| 36 | | v |
| 37 | -------------------> platform_infrastructure |
| 38 | ``` |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 39 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 40 | An example for such dependency |
| 41 | is QuicClock. |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 42 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 43 | Or |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 44 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 45 | ``` |
| 46 | application -> quic_core -> quic_platform_api |
| 47 | | ^ |
| 48 | | | |
| 49 | | v |
| 50 | -------------------> quic_platform_impl |
| 51 | | | |
| 52 | | v |
| 53 | -------------------> platform_infrastructure |
| 54 | ``` |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 55 | |
danzh | 1834770 | 2019-06-21 11:15:12 -0700 | [diff] [blame] | 56 | An example for such dependency |
| 57 | is QuicMemSlice. |
nharper | 6153bc7 | 2019-05-08 12:04:34 -0700 | [diff] [blame] | 58 | |
| 59 | # Documentation of each API and its usage. |
| 60 | |
| 61 | QuicMemSlice |
| 62 | : QuicMemSlice is used to wrap application data and pass to QUIC stream's |
| 63 | write interface. It refers to a memory block of data which should be around |
| 64 | till QuicMemSlice::Reset() is called. It's upto each platform, to implement |
| 65 | it as reference counted or not. |
| 66 | |
| 67 | QuicClock |
| 68 | : QuicClock is used by QUIC core to get current time. Its instance is created |
| 69 | by applications and passed into QuicDispatcher and |
| 70 | QuicConnectionHelperInterface. |
| 71 | |
| 72 | TODO(b/131224336) add document for other APIs |