The document provides an overview of the AWS SDK for C++, including its core features such as credential management, asynchronous requests, rate limiting, error handling, and memory allocation. It also discusses how to override the HTTP/TLS stack and integrate high-level APIs. The presentation encourages attendees to contribute high-level APIs and send pull requests to the SDK's GitHub repository.

1. © 2015, Amazon Web Services, Inc. or its Affiliates. All rights reserved.
Preston Tamkin and Jonathan Henson
October 2015
DEV204
AWS SDK for C++
Building High-Performance, Native Cloud
Apps in C++

2. Agenda
• Overview of the AWS SDK for C++
• github.com/awslabs/aws-sdk-cpp
• Core library features
• Credential management
• Logging
• Asynchronous requests
• Rate limiting
• Error handling
• Memory allocation
• Streaming
• Overriding the HTTP/TLS stack
• High-level APIs overview

3. Getting started
What is it?
• Modern C++ language bindings for AWS
• Generated service clients + high-level APIs
Source
• github.com/awslabs/aws-sdk-cpp
Build Prerequisites
• C++11-compatible compiler
• CMake
• A HTTP/TLS implementation for your platform
– We ship Curl, WinHTTP, and WinINet interfaces

4. Sample
1 DynamoDBClient client;
2 AttributeValue hashKeyAttribute;
3 hashKeyAttribute.SetS(“SampleHashKeyValue”);
4 AttributeValue valueAttribute;
5 valueAttribute.SetS(“SampleValue”);
6
7 PutItemRequest putItemRequest;
8 putItemRequest.WithTableName(“TestTableName”)
9 .AddItem(“HashKey”, hashKeyAttribute).AddItem(“Value”, valueAttribute);
10
11 client.PutItem(putItemRequest);
12
13

5. Credential management
• AWSCredentialsProvider interface
• Core library includes
• EnvironmentAWSCredentialsProvider
• ProfileConfigFileAWSCredentialsProvider
• InstanceProfileCredentialsProvider
• DefaultAWSCredentialsProviderChain (chains the above)
• Amazon Cognito identity providers included
• Custom providers supported

6. Credentials
1 auto credentialProvider = Aws::MakeShared<InstanceProfileCredentialsProvider >(“re:InventSample”);
2 DynamoDBClient client(credentialProvider);

7. SDK logging
• Internal logging interface for SDK diagnostics
• No external dependencies
• Default implementation logs to local filesystem

8. Logging
1 Aws::Utils::Logging::InitializeAWSLogging(Aws::MakeShared<Aws::Utils::Logging::DefaultLogSystem>(“re:InventSample”,
2 Aws::Utils::Logging::LogLevel::Trace, “aws_"));
3 auto credentialProvider = Aws::MakeShared<InstanceProfileCredentialsProvider >(“re:InventSample”);
4 DynamoDBClient client(credentialProvider);
15 Aws::Utils::Logging::ShutdownAWSLogging();

9. ClientConfiguration
• Optional parameter for client constructors
• Plain old data
• Contains per-client configuration and overrides

10. Async
• All generated operations have an async version
• Async requests notify your callback function
• Callback receives client, request, outcome, and
optional context objects
• Pluggable custom executor for more control

11. Async
1 void putItemFinished(const DynamoDBClient* client, const PutItemRequest& request,
2 const PutItemOutcome& outcome,
3 const std::shared_ptr<AsyncContext>& context)
4 {
5 If (outcome.IsSuccess())
6 {
7 SEND_QUEUE.erase(context->GetUUIID());
8 }
9 }
10
11 auto context = Aws::MakeShared<AsyncContext>(“re:invent sample”);
12 context.SetUUID(“UniqueRequestKey”);
13 SEND_QUEUE[“UniqueRequestKey”] = putItemRequest;
14 client.PutItemAsync(putItemRequest, &putItemFinished, context);

12. Async with member functions
1 void ReinventSample::putItemFinished(const DynamoDBClient* client, const PutItemRequest& request,
2 const PutItemOutcome& outcome,
3 const shared_ptr<AsyncContext>& context)
7 m_sendQueue.erase(context->GetUUIID());
13 m_sendQueue[“UniqueRequestKey”] = putItemRequest;
std::bind(&ReinventSample::putItemFinished, this, std::placeholders::_1,
15 std::placeholders::_2, std::placeholders::_3, std::placeholders::_4)

13. Asynchronous executor
• Default executor will spawn a detached thread
• Implement executor for more control
• Use this to tie asynchronous calls to your system’s
custom thread pool

14. Asynchronous executor
1 #include <aws/core/utils/threading/Executor.h>
2
3 class CustomExecutor : public Aws::Utils::Threading::Executor
4 {
5 public:
6 CustomExecutor(MySystemsExecutorImpl* executor) : m_executor(executor)
7
8 protected:
9 bool SubmitToThread(std::function<void()>&& task) override
10 {
11 return m_executor->QueueTask(std::forward<std::function<void()>(task));
12 }
13
14 private:
15 MySystemsExecutorImpl* m_executor;
16 };

15. Asynchronous executor
1 ClientConfiguration config;
2 auto mySystemsExecutorImpl = applicationConfiguration->GetExecutor();
3 config.executor = mySystemsExecutorImpl;
4
5 DynamoDBClient client(config);
client.PutItemAsync(putItemRequest, &putItemFinished);

16. Rate limiting
• Client-side bandwidth throttling at the HTTP layer
• Configurable separately for each client and each
directionality (uploads and downloads)

17. Rate limiting
1 class CustomRateLimiter : public Aws::Utils::RateLimits::RateLimiterInterface
2 {
3 public:
4 ….
5
6 DelayType ApplyCost(int64_t cost) override
7 {
8 m_availableBandwidth -= cost;
9 return m_availableBandwidth > 0 ? DelayType(0) : DelayType(0 – m_availableBandwidth);
10 }
11
12 void ApplyAndPayForCost(int64_t cost) override
13 {
14 std::this_thread::sleep_for(ApplyCost(cost));
15 m_availableBandwidth += cost;
16 }
17 …
18 };

18. Rate limiting
1 ClientConfiguration config;
2 auto downloadLimiter = Aws::MakeShared<CustomRateLimiter>(“re:InventSample”, FIVE_MB);
3 auto uploadLimiter =
4 Aws::MakeShared<CustomRateLimiter>(“re:InventSample”, TWO_HUNDRED_KB);
5 config.readRateLimiter = downloadLimiter;
6 config.writeRateLimiter = uploadLimiter;
7 DynamoDBClient client(config);

19. Rate limiting
Recommendations and things to know:
• Default rate limiter implementation probably does what
you want. (#include
<aws/core/utils/ratelimiter/DefaultRateLimiter.h> )
• Calculation made at IO time not request size.

20. Error handling
• No exceptions used internally or thrown externally
• Performance and flexibility reasons
• SDK is exception-safe
• Exceptions are safe to use in your application

21. Error handling
• Requests return an ‘Outcome’ object.
• An ‘Outcome’ is either successful with a result payload
or unsuccessful with an error payload
• Errors closely match exception names from other
SDKs

22. Error handling and the outcome pattern
1 PutItemOutcome outcome = client.PutItem(putItemRequest);
2 If (outcome.IsSuccess())
3 {
4 std::cout << outcome.GetResult().GetConsumedCapacity().GetCapacityUnits() <<
5 “ Capacity Consumed” << std::endl;
6 }
7 else
8 {
9 If (outcome.GetError().GetErrorType() == DynamoDbErrors::CONDITIONAL_CHECK_FAILED)
10 {
11 std::cout << “Conditional Write failed. “
12 << “ Message: “ << outcome.GetError().GetMessage() << std::endl;
13 }
14 else
15 {
16 std::cout << “Unexpected error “ << outcome.GetError().GetMessage() << std::endl;
17 }
18 }

23. Retry strategies
• Default retry strategy
• Overridable per client
• Offers more granular support your application

24. Retry strategies
1 class ExponentialBackOffStrategy : public Aws::Client::RetryStrategy
2 {
3 public:
4 bool ShouldRetry(const AWSError<CoreErrors>& error, long attemptedRetries) const
5 {
6 If (attemptedRetries < 5) return error.ShouldRetry();
7
8 return false;
9 }
10
11 long CalculateDelayBeforeNextRetry(const AWSError<CoreErrors>& error, long attemptedRetries) const
12 {
13 If (attemptedRetries == 0) return 0;
14
15 return (1 << attemptedRetries) * 25;
16 }
17 };
18

25. Retry strategies
1 ClientConfiguration config;
2 auto retryStrategy =
3 Aws::MakeShared<ExponentialBackoffStrategy>(“re:inventSample”);
4 config.retryStrategy = retryStrategy;
5 DynamoDBClient client(config);

26. Memory allocation
• Configured at compile time
• Custom Allocators installed at runtime
• Default forces allocation into single allocator
• On by default for dynamic libraries
• What about the STL?

27. Memory allocation
1 class DlMallocMemorySystem : public MemorySystemInterface
2 {
3 public:
4 ~DlMallocMemorySystem() = default;
5
6 void Begin() override {}
7 void End() override {}
8
9 void* AllocateMemory(std::size_t blockSize, std::size_t alignment, const char* allocationTag = nullptr) override
10 {
11 return dlmalloc(blockSize);
12 }
13
14 void FreeMemory(void* memoryPtr) override
15 {
16 dlfree(memoryPtr);
17 }
18 };

28. Memory allocation
1 DlMallocMemorySystem dlMallocMemorySystem;
2 Aws::Utils::Memory::InitializeAWSMemorySystem(dlMallocMemorySystem);
14 Aws::Utils::Memory::ShutdownAWSMemorySystem();

29. Memory allocation
What about the Standard Template Library?
• Use AWS-defined STL types (Aws::Vector, Aws::String,
Aws::Map, Aws::IOStream, etc.)
• Automatically resolves allocator
• Compile time switch
• Most APIs take primitives as well

30. Memory allocation
General advice
• Use custom memory management with dynamic
linking -- especially on Windows
• Do not use STL containers directly
• Do not use new or delete directly
• Do not use std smart pointer APIs directly
• Use –DAWS_CUSTOM_MEMORY_MANAGEMENT
w/ custom memory management

31. Streaming requests and responses
• Some payloads are not typed (example: Amazon S3
GetObject, PutObject)
• Use the STL IOStream interface.
• Defaults to underlying StringBuf
• Easily overridable

32. Streaming requests
1 S3Client client;
2 PutObjectRequest putObjectRequest;
3 putObjectRequest.SetBucketName(“reinvent_sample_bucket”);
4 putObjectRequest.SetKeyName(“reinvent_sample_key”);
5
6 auto fileToUpload = Aws::MakeShared<Aws::FStream>(“re:InventSample”,
7 “users/me/toUpload/fileToUpload.png”, std::ios_in);
8 putObjectRequest.SetBody(fileToUpload);
9
10 auto outcome = client.PutObject(putObjectRequest);
11
12

33. Streaming responses
1 S3Client client;
2 GetObjectRequest getObjectRequest;
3 getObjectRequest.SetBucketName(“reinvent_sample_bucket”);
4 getObjectRequest.SetKeyName(“reinvent_sample_key”);
5 getObjectRequest.SetResponseStreamFactory(
6 [](){
7 return Aws::New<Aws::FStream>(“re:InventSample”, “/users/me/downloads/filename.png”,
8 std::ios_base::in | std::ios_base::out | std::ios_base::trunc);
9 });
10
11 auto outcome = client.GetObject(getObjectRequest);
12 ….

34. Overriding the HTTP/TLS stack
I want to use my own IO stack. What do I do?
• HTTP stacks can be injected into clients
• Implement your own HttpClient
• Simply override the HttpClientFactory in your
ClientConfiguration

35. Overriding the HTTP/TLS stack
1 class LibUVWithSignalToNoiseHttpClient : public Aws::Http::HttpClient
2 {
3 public:
4 virtual ~LibUVWithSignalToNoiseHttpClient () {}
5
6 std::shared_ptr<HttpResponse> MakeRequest(HttpRequest& request,
7 Aws::Utils::RateLimits::RateLimiterInterface* readLimiter = nullptr,
8 Aws::Utils::RateLimits::RateLimiterInterface* writeLimiter = nullptr) const override;
9 };
10

36. Overriding the HTTP/TLS stack
1 class LibUVWithSignalToNoiseHttpClientFactory : public Aws::Http::HttpClientFactory
2 {
3 public:
4 virtual ~LibUVWithSignalToNoiseHttpClientFactory() {}
5
6 std::shared_ptr<HttpClient> CreateHttpClient
7 (const Aws::Client::ClientConfiguration& clientConfiguration) const override;
8
9 virtual std::shared_ptr<HttpRequest> CreateHttpRequest(const Aws::String& uri, HttpMethod method,
10 const Aws::IOStreamFactory& streamFactory) const override;
11
12 virtual std::shared_ptr<HttpRequest> CreateHttpRequest(const URI& uri, HttpMethod method,
13 const Aws::IOStreamFactory& streamFactory) const override;
14 };

37. Overriding the Http/TLS stack
1 auto httpClientFactory = Aws::MakeShared<LibUVWithSignalToNoiseHttpClientFactory>(“re:InventSample”);
2 DynamoDBClient client(credentialProvider, config, httpClientFactory);

38. High-level APIs
• Amazon Cognito identity providers
• Amazon S3 Transfer Manager
• Queues-like interface for Amazon SQS
• Access management API for IAM

39. High-level APIs
1 auto credentialsProvider =
2 Aws::MakeShared<CognitoCachingAnonymousCredentialsProvider>(“re:invent sample”,
3 “55216815”, “us-east-1:65814ddc-1479-4dfe-9bab-254541asd2fb”);
4
5 DynamoDBClient dynamoDbClient(credentialsProvider);
6
Identity management with an anonymous identity pool

40. High-level APIs
1 auto identityProvider =
2 Aws::MakeShared<DefaultPersistentCognitoIdentityProvider>(“re:invent sample”);
3 Aws::Map<Aws::String, LoginAccessTokens> tokens;
4 tokens[“www.amazon.com”] = LoginAccessTokens { “aegedeev”, “bdekibnkoga”, ONE_HOUR };
5 identityProvider->PersistLogins(tokens);
6
7 auto credentialsProvider =
8 Aws::MakeShared<CognitoCachingAuthenticatedCredentialsProvider>(“re:invent sample”,
9 “55216815”, “us-east-1:65814ddc-1479-4dfe-9bab-254541asd2fb”,
10 identityProvider);
11 DynamoDBClient dynamoDbClient(credentialsProvider);
Identity management with an authenticated identity pool

41. High-level APIs
1 auto s3Client = Aws::MakeShared<S3Client>(“re:invent sample”);
2 TransferClient transferClient(s3Client, TransferClientConfiguration { 10, nullptr } );
3
4 auto uploadFileRequest =
5 transferClient.UploadFile(“/home/user/customer/myDatabase.frm”,
6 “sample_bucket”, “sample_key”, “application/octet-stream”);
Uploading a large file with Transfer Manager

42. High-level APIs
1 auto sqsClient = Aws::MakeShared<SQSClient>(“reinvent sample”);
2 SQSQueue queue(sqsClient, “sample_queue”, FIFTEEN_SEC);
3 queue.SetMessageRecievedEventHandler(
4 std::bind(&ReinventSample::OnMessageRecieved, this,
5 std::placeholders::_1, std::placeholders::_2, std::placeholders::_3));
6 queue.EnsureQueueIsInitialized();
7 queue.StartPolling();
8
9 void ReinventSample::OnMessageRecieved(const Queue* queue,
10 const Message& message , bool& deleteMessage)
11 {
12 auto msgBody = message.GetBody();
13 deleteMessage = SEND_IPC_MESSAGE(Q_ID, msgBody) != -1;
14 }
Receiving async message notifications via queues

43. High-level APIs
Contributing high-level APIs
• Please do!
• Follow contribution guidelines outlined in readme
• Use constructor injection for low-level clients

44. Takeaways
• Overview of the AWS SDK for C++
• github.com/awslabs/aws-sdk-cpp
• Core library features
• Credential management
• Logging
• Asynchronous requests
• Rate limiting
• Error handling
• Memory allocation
• Streaming
• Overriding the HTTP/TLS stack
• High-level APIs overview

45. © 2015, Amazon Web Services, Inc. or its Affiliates. All rights reserved.
Send us pull requests @
github.com/awslabs/aws-sdk-cpp

46. Thank you!

47. Remember to complete
your evaluations!