meta request: support for should_continue cancellation callback

[grrtrr]

Add a boolean continue_callback, which polls a request-cancellation flag set by the user. This matches the use-case of the ContinueRequestHandler / ContinueRequest / ShouldContinue boolean functions used by aws-sdk-cpp.

Passive polling is preferred over active cancellation, since the latter would require to store a reference to the s3 meta request. The polling function is evaluated at the following points during the lifetime of the meta request:

1. Request preparation (aws_s3_meta_request_prepare_request).
2. Request update (the .update handler invoked via aws_s3_meta_request_update).
3. Http stream completion (.on_complete handler invoking aws_s3_meta_request_send_request_finish_default).
4. Writing download data (aws_s3_meta_request_stream_response_body_synced).

If a continue_callback is provided and if it returns false at any of these 4 evaluation times, the meta request completes with the error_code AWS_ERROR_S3_CANCELED.

By using a boolean flag in the body of the function, the polling overhead can be kept minimal.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[codecov-commenter]

Codecov Report

Merging #238 (01f878e) into main (c95ad5c) will increase coverage by 0.04%. The diff coverage is 100.00%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #238      +/-   ##
==========================================
+ Coverage   87.01%   87.05%   +0.04%     
==========================================
  Files          16       16              
  Lines        4036     4041       +5     
==========================================
+ Hits         3512     3518       +6     
+ Misses        524      523       -1     

Impacted Files	Coverage Δ
source/s3_meta_request.c	92.82% <100.00%> (+0.04%)	:arrow_up:
source/s3_client.c	86.66% <0.00%> (+0.01%)	:arrow_up:
source/s3_auto_ranged_put.c	91.94% <0.00%> (+0.19%)	:arrow_up:

[grrtrr]

Hi @jmklix why was this closed without comments. Is there an alternative that can be used and where is it documented?

As it stands, S3Crt requests can not be canceled at the moment.

[TingDaoK]

with https://github.com/awslabs/aws-c-s3/pull/395, we now cancel all the in-flight requests. It's over-complicate the behavior for user to control for each requests. Unless you have a strong opinion with use case, I don't see a point to keep the requests in-flight when you decided to cancel the meta request.