Use permalinks in buffering.md (#1038)

Author: yuma-m

docs/buffering.md

@@ -1,6 +1,6 @@
 ### Producer SDK buffering
 
-Producer SDK PIC handles the frame buffering by separating the physical storage called Content Store from the logical view known as Content View. The Content Store is a simple storage based on an internal heap implementation. The DeviceInfo.StorageInfo https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1012 controls the type of the storage and the amount of memory to reserve. The Content Store is shared among all of the streams within the client object. Content View, on the other hand, contains the temporal logic of the frames that are in the buffer. The Content View is created per each stream. As the frames are pushed to the SDK using PutFrame API, the frames are being packaged and put in the Content Store and the reference with timestamp information is being produced into the Content View. 
+Producer SDK PIC handles the frame buffering by separating the physical storage called Content Store from the logical view known as Content View. The Content Store is a simple storage based on an internal heap implementation. The DeviceInfo.StorageInfo https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1115 controls the type of the storage and the amount of memory to reserve. The Content Store is shared among all of the streams within the client object. Content View, on the other hand, contains the temporal logic of the frames that are in the buffer. The Content View is created per each stream. As the frames are pushed to the SDK using PutFrame API, the frames are being packaged and put in the Content Store and the reference with timestamp information is being produced into the Content View. 
 
 
 ![GitHub Logo](/docs/Content_View_Storage.png)
@@ -9,12 +9,12 @@ Producer SDK PIC handles the frame buffering by separating the physical storage
 ### Content Store
 
 Content store is an abstraction of the underlying storage that can have different implementations. By default, the implementation is based on low-fragmentation, tightly packed heap which can provide good performance characteristics processing "rolling window"-like allocations of similar sizes with minimal waste of memory/fragmentation. Moreover, the content store abstraction allows for dynamic resizing and indirect mapping which are useful in cases of "hybrid" store chaining with spill-over (for example RAM-based heap with spill-over on eMMC-backed storage). 
-Storage overflow callback (https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1409) will be called when there is less than 5% of storage available.
+Storage overflow callback (https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1579) will be called when there is less than 5% of storage available.
 
 
 ### Content View
 
-Content View can be thought of as a list of frame information that includes timestamps, flags and the handle to the actual storage. The new frames are produced into the Head (and the head moves forward) and the frames are being read from Current pointer. The last frame is pointed to by Tail pointer. The tail moves forward either when the SDK receives Persisted ACK or on buffer pressure when the duration window reaches the buffer duration that's specified in StreamInfo.StreamCaps https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L882. As the frames are pushed out of the tail, their content is being purged from the Content Store. If the Tail catches up with Current, a dropped frame callback will be called to notify the application of dropped frames. 
+Content View can be thought of as a list of frame information that includes timestamps, flags and the handle to the actual storage. The new frames are produced into the Head (and the head moves forward) and the frames are being read from Current pointer. The last frame is pointed to by Tail pointer. The tail moves forward either when the SDK receives Persisted ACK or on buffer pressure when the duration window reaches the buffer duration that's specified in StreamInfo.StreamCaps https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L982. As the frames are pushed out of the tail, their content is being purged from the Content Store. If the Tail catches up with Current, a dropped frame callback will be called to notify the application of dropped frames. 
 
 The production into the buffer is done at frame granularity (PutFrame takes an entire frame) whereas the Networking stack reading the frame bits operates on bit granularity. The MKV packaging format allows the frames to be "streamable" where the frame bits can be streamed out before the last frame of the fragment can be produced into the buffer, thus, making low-latency streaming possible.
 
@@ -58,17 +58,17 @@ Frames can be omitted by not only "dropping" them but also "skipping" them. Ther
 
 ### Stream staleness
 
-KVS streaming abstracts the actual networking protocol and doesn't rely on the network-level ACKs. Moreover, the network level ACKs are still insufficient for guaranteeing the delivery of the video data to the backend. Stream staleness is calculated by measuring the time between the successive Buffering ACKs. If this time is above the threshold specified in StreamCaps (https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L941) the StreamConnectionStaleFunc callback will be executed. The default handler for this callback will reset the connection but the applications could choose to perform other actions if needed.
+KVS streaming abstracts the actual networking protocol and doesn't rely on the network-level ACKs. Moreover, the network level ACKs are still insufficient for guaranteeing the delivery of the video data to the backend. Stream staleness is calculated by measuring the time between the successive Buffering ACKs. If this time is above the threshold specified in StreamCaps (https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1041) the StreamConnectionStaleFunc callback will be executed. The default handler for this callback will reset the connection but the applications could choose to perform other actions if needed.
 
 
 ### Stream rollback
 
-KVS SDK is configured by default to re-connect/re-stream on error/disconnection as set in StreamInfo.StreamCaps.recoverOnError https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L926 
+KVS SDK is configured by default to re-connect/re-stream on error/disconnection as set in StreamInfo.StreamCaps.recoverOnError https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1012 
 
 During streaming, the connection could get disconnected or an error could be generated by the backend in a form of an error ACK. In these cases, the SDK attempts to drive the internal state machinery through the states and reconnect. Once reconnected, it will need to make a decision from where to restart the streaming in order to still provide durability guarantees and ensure that the frames in the internal buffer are persisted. 
 
 1) Determine the timestamp on the internal Content View timeline on when the issue happens. For example, if it's a simple network disconnect then the Current from the content view is used whereas if there is an error ACK causing the termination of the connection and if we have a timestamp specified in the ACK then we set the time to the timestamp specified in the error ACK.
 2) Check the reason for disconnection. Some error indicate that the stream has an issue (for example error ACKs) in which case the SDK determines that the processing host is still alive and the data is still in it's buffer but the fragment which errored is inherently can not be ingested even if it's retried so it needs to be skipped. There are other error class category that indicate a simple networking timeout for example, in which case we determine that the host might still be alive and the so-far ingested but not yet persisted data might still be in the ingestion host internal buffer. While, there are other cases that we determine for sure that the host itself is likely to be dead and the data in the buffer that hasn't been durably persisted is gone.
-3) If the error is determined to be caused by a "dead" host then the rollback should roll all the way to the fragment that has a timestamp of last Persisted ACK fragments next timestamp within the buffer or the rollback duration - whichever is less. Rollback duration is specified in StreamInfo.StreamCaps.replayDuration https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/master/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L948
+3) If the error is determined to be caused by a "dead" host then the rollback should roll all the way to the fragment that has a timestamp of last Persisted ACK fragments next timestamp within the buffer or the rollback duration - whichever is less. Rollback duration is specified in StreamInfo.StreamCaps.replayDuration https://github.com/awslabs/amazon-kinesis-video-streams-pic/blob/032aa7843f58151f41fb0ab9b473a02338e6f76f/src/client/include/com/amazonaws/kinesis/video/client/Include.h#L1034
 4) If the error is determined to be caused by a connection issue then the host is likely to be "alive" and the not-yet persisted data is accessible from within the hosts buffer. In this case the rollback happens from the current position back until we 'replayDuration' or last Received ACK fragments next fragment. NOTE: in both 3) and 4) the Received and Persisted ACK fragment have been already ingested as the ACK timestamp for Persisted and Received ACKs is the timestamp of the first frame of the Fragment being ACK-ed.
 5) Restarted stream will skip over the fragments which are marked as "skip". These are the fragments that have been determined to cause issues with the backend parsing (error ACK).