az_context.h File Reference

Context for canceling long running operations. More...

#include <azure/core/az_result.h>
#include <stddef.h>
#include <stdint.h>
#include <azure/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Data Structures
struct	az_context
	A context is a node within a tree that represents expiration times and key/value pairs. More...

Typedefs
typedef struct az_context	az_context
	A context is a node within a tree that represents expiration times and key/value pairs.

Functions
AZ_NODISCARD az_context	az_context_create_with_expiration (az_context const *parent, int64_t expiration)
	Creates a new expiring az_context node that is a child of the specified parent. More...
AZ_NODISCARD az_context	az_context_create_with_value (az_context const *parent, void const *key, void const *value)
	Creates a new key/value az_context node that is a child of the specified parent. More...
void	az_context_cancel (az_context *ref_context)
	Cancels the specified az_context node; this cancels all the child nodes as well. More...
AZ_NODISCARD int64_t	az_context_get_expiration (az_context const *context)
	Returns the soonest expiration time of this az_context node or any of its parent nodes. More...
AZ_NODISCARD bool	az_context_has_expired (az_context const *context, int64_t current_time)
	Returns true if this az_context node or any of its parent nodes' expiration is before the current_time. More...
AZ_NODISCARD az_result	az_context_get_value (az_context const *context, void const *key, void const **out_value)
	Walks up this az_context node's parents until it find a node whose key matches the specified key and returns the corresponding value. More...

Variables
az_context	az_context_application
	The application root az_context instances. More...

Detailed Description

Context for canceling long running operations.

Note

You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Function Documentation

az_context_cancel()

void az_context_cancel

(

az_context *

ref_context

)

Cancels the specified az_context node; this cancels all the child nodes as well.

Parameters

[in,out]

ref_context

A pointer to the az_context node to be canceled.

az_context_create_with_expiration()

AZ_NODISCARD az_context az_context_create_with_expiration	(	az_context const *	parent,
		int64_t	expiration
	)

Creates a new expiring az_context node that is a child of the specified parent.

Parameters

[in]	parent	The az_context node that is the parent to the new node.
[in]	expiration	The time when this new node should be canceled.

Returns

The new child az_context node.

az_context_create_with_value()

AZ_NODISCARD az_context az_context_create_with_value	(	az_context const *	parent,
		void const *	key,
		void const *	value
	)

Creates a new key/value az_context node that is a child of the specified parent.

Parameters

[in]	parent	The az_context node that is the parent to the new node.
[in]	key	A pointer to the key of this new az_context node.
[in]	value	A pointer to the value of this new az_context node.

Returns

The new child az_context node.

az_context_get_expiration()

AZ_NODISCARD int64_t az_context_get_expiration

(

az_context const *

context

)

Returns the soonest expiration time of this az_context node or any of its parent nodes.

Parameters

[in]

context

A pointer to an az_context node.

Returns

The soonest expiration time from this context and its parents.

az_context_get_value()

AZ_NODISCARD az_result az_context_get_value	(	az_context const *	context,
		void const *	key,
		void const **	out_value
	)

Walks up this az_context node's parents until it find a node whose key matches the specified key and returns the corresponding value.

Parameters

[in]	context	The az_context node in the tree where checking starts.
[in]	key	A pointer to the key to be scanned for.
[out]	out_value	A pointer to a void const* that will receive the key's associated value if the key is found.

Returns

An az_result value indicating the result of the operation.

Return values

AZ_OK	The key is found.
AZ_ERROR_ITEM_NOT_FOUND	No nodes are found with the specified key.

az_context_has_expired()

AZ_NODISCARD bool az_context_has_expired	(	az_context const *	context,
		int64_t	current_time
	)

Returns true if this az_context node or any of its parent nodes' expiration is before the current_time.

Parameters

[in]	context	A pointer to the az_context node to check.
[in]	current_time	The current time.

Variable Documentation

az_context_application

az_context az_context_application

extern

The application root az_context instances.

The az_context_application never expires but you can explicitly cancel it by passing its address to az_context_cancel() which effectively cancels all its az_context child nodes.