alexaClientSDK::avsCommon::avs::attachment::AttachmentManager Class Reference

#include <AttachmentManager.h>

Inheritance diagram for alexaClientSDK::avsCommon::avs::attachment::AttachmentManager:

Collaboration diagram for alexaClientSDK::avsCommon::avs::attachment::AttachmentManager:

Public Types
enum	AttachmentType { AttachmentType::IN_PROCESS }

Public Member Functions
	AttachmentManager (AttachmentType attachmentType)
std::string	generateAttachmentId (const std::string &contextId, const std::string &contentId) const override
bool	setAttachmentTimeoutMinutes (std::chrono::minutes timeoutMinutes) override
std::unique_ptr< AttachmentWriter >	createWriter (const std::string &attachmentId, utils::sds::WriterPolicy policy=avsCommon::utils::sds::WriterPolicy::ALL_OR_NOTHING) override
std::unique_ptr< AttachmentReader >	createReader (const std::string &attachmentId, utils::sds::ReaderPolicy policy) override
Public Member Functions inherited from alexaClientSDK::avsCommon::avs::attachment::AttachmentManagerInterface
virtual	~AttachmentManagerInterface ()=default

Static Public Member Functions
static std::shared_ptr< AttachmentManagerInterface >	createInProcessAttachmentManagerInterface ()

Static Public Attributes
static constexpr std::chrono::minutes	ATTACHMENT_MANAGER_TIMOUT_MINUTES_DEFAULT = std::chrono::hours(12)
static constexpr std::chrono::minutes	ATTACHMENT_MANAGER_TIMOUT_MINUTES_MINIMUM = std::chrono::minutes(1)

Detailed Description

This class allows the decoupling of attachment readers and writers from the management of attachments.

This class is thread safe.

A design principle of the Attachment class is that each attachment will have at most one reader and writer.

Application code may query the manager for a reader and writer object at any time, and in any order.

Note

Resource management is currently implemented by a timeout approach. This does have the following limitations:

• An AttachmentReader or AttachmentWriter has reference to a shared buffer resource for the actual data. This buffer will remain in existence until both the Reader and Writer have been destroyed.
• Therefore, application code should ensure that Readers and Writers are destroyed when no longer needed.
• The AttachmentManager will always satisfy a request to create a Reader or Writer - it will not currently enforce a maximum resource limit.
• ACSDK-254 will address this by enforcing such limits. It should also be noted however, that a well behaving application may not observe much difference - the future implementation will forcibly close the oldest Attachment to make space for the new one. For a system reading and writing a small set of attachments at any given time, the AttachmentManager should not need to step in and take such action.

Member Enumeration Documentation

AttachmentType

enum alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::AttachmentType

strong

A local enumeration allowing the createReader call to act as a factory function for the underlying attachments. This enumeration need not include all specializations of the Attachment class, only the ones that make sense for the AttachmentManager to manage.

Enumerator
IN_PROCESS	This value corresponds to the InProcessAttachment class.

Constructor & Destructor Documentation

AttachmentManager()

alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::AttachmentManager

(

AttachmentType

attachmentType

)

Constructor.

Deprecated:

Parameters

attachmentType

The type of attachments which will be managed.

Member Function Documentation

createInProcessAttachmentManagerInterface()

static std::shared_ptr<AttachmentManagerInterface> alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::createInProcessAttachmentManagerInterface ( )

static

Factory for creating IN_PROCESS instances of AttachmentManagerInterface.

Returns

An IN_PROCESS instances of AttachmentManagerInterface.

createReader()

std::unique_ptr<AttachmentReader> alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::createReader ( const std::string &  attachmentId, utils::sds::ReaderPolicy  policy  )

overridevirtual

Returns a pointer to an AttachmentReader.

Note

Calls to createReader and createWriter may occur in any order.

Parameters

attachmentId	The id of the Attachment.
policy	The AttachmentReader policy, which determines the semantics of the AttachmentReader.read().

Returns

An AttachmentReader.

Implements alexaClientSDK::avsCommon::avs::attachment::AttachmentManagerInterface.

Reimplemented in alexaClientSDK::avsCommon::utils::TestableAttachmentManager.

createWriter()

std::unique_ptr<AttachmentWriter> alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::createWriter ( const std::string &  attachmentId, utils::sds::WriterPolicy  policy = avsCommon::utils::sds::WriterPolicy::ALL_OR_NOTHING  )

overridevirtual

Returns a pointer to an AttachmentWriter.

Note

Calls to createReader and createWriter may occur in any order.

Parameters

attachmentId	The id of the Attachment.
policy	The WriterPolicy that the AttachmentWriter should adhere to.

Returns

An AttachmentWriter.

Implements alexaClientSDK::avsCommon::avs::attachment::AttachmentManagerInterface.

Reimplemented in alexaClientSDK::avsCommon::utils::TestableAttachmentManager.

generateAttachmentId()

std::string alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::generateAttachmentId ( const std::string &  contextId, const std::string &  contentId  ) const

overridevirtual

Creates an attachmentId given two particular strings - the contextId and the contentId. Generally, contextId allows disambiguation when two attachment contentIds are not guaranteed to be unique. This function provides a consistent way for different parts of application code to combine contextId and contentId into a single string. Clearly, both the reader and writer of a given attachment need to call this function with the same two strings.

As an example of usage, if an application has several sources of attachments, for example two audio providers, then one pair of contextId / contentId strings might be: { "AudioProvider1", "Attachment1" }. If the other audio provider creates an attachment, then the pair: { "AudioProvider2", "Attachment1" } allows the contextId to disambiguate what happens to be identical contentIds.

If this function is called with one or both strings being empty, then the combine will not be performed. In the case of both strings being empty, an empty string will be returned. If only one string is non-empty, then that string will be returned.

Parameters

contextId	The contextId, which generally reflects the source of the Attachment.
contentId	The contentId, which is considered unique when paired with a particular contextId.

Returns

The combined strings, which may be then used as a single attachmentId, per the logic outlined above.

Implements alexaClientSDK::avsCommon::avs::attachment::AttachmentManagerInterface.

Reimplemented in alexaClientSDK::avsCommon::utils::TestableAttachmentManager.

setAttachmentTimeoutMinutes()

bool alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::setAttachmentTimeoutMinutes ( std::chrono::minutes  timeoutMinutes )

overridevirtual

Sets the timeout parameter which is used to ensure unused attachments are eventually cleaned up. This time is specified in minutes. An unused attachment is defined as an attachment for which only a reader or writer was created. Such an Attachment is waiting to be either produced or consumed.

If this function is not called, then the timeout is set to a default value specified by the implementation.

The timeout cannot be set lower than an implementation specific minimum, since too low a timeout could cause attachments to be removed before both reader and writer have had time to request it.

Parameters

timeoutMinutes

The timeout, expressed in minutes. If this is less than the minimum, then the setting will not be updated, and the function will return false.

Returns

Whether the timeout was set ok.

Implements alexaClientSDK::avsCommon::avs::attachment::AttachmentManagerInterface.

Reimplemented in alexaClientSDK::avsCommon::utils::TestableAttachmentManager.

Member Data Documentation

ATTACHMENT_MANAGER_TIMOUT_MINUTES_DEFAULT

constexpr std::chrono::minutes alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::ATTACHMENT_MANAGER_TIMOUT_MINUTES_DEFAULT = std::chrono::hours(12)

static

This is the default timeout value for attachments. Any attachment which is inspected in the removeExpiredAttachmentsLocked() call, and whose lifetime exceeds this value, will be released.

ATTACHMENT_MANAGER_TIMOUT_MINUTES_MINIMUM

constexpr std::chrono::minutes alexaClientSDK::avsCommon::avs::attachment::AttachmentManager::ATTACHMENT_MANAGER_TIMOUT_MINUTES_MINIMUM = std::chrono::minutes(1)

static

This is the minimum timeout value for attachments. setAttachmentTimeoutMinutes() will not accept a value lower than this.

---

The documentation for this class was generated from the following file:

• /workplace/avs-device-sdk/AVSCommon/AVS/include/AVSCommon/AVS/Attachment/AttachmentManager.h