Package software.amazon.awssdk.crt

Class CrtResource

java.lang.Object

software.amazon.awssdk.crt.CrtResource

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

AwsSigningConfig, ClientBootstrap, ClientConnection, ClientConnectionContinuation, CredentialsProvider, EccKeyPair, EventLoopGroup, HostResolver, HttpClientConnection, HttpClientConnectionManager, HttpStream, Message, MqttClient, MqttClientConnection, MqttConnectionConfig, Pkcs11Lib, S3Client, S3MetaRequest, ServerBootstrap, ServerConnection, ServerConnectionContinuation, ServerListener, SocketOptions, TlsContext, TlsContextOptions, TlsContextPkcs11Options

public abstract class CrtResource
extends Object
implements AutoCloseable

This wraps a native pointer and/or one or more references to an AWS Common Runtime resource. It also ensures that the first time a resource is referenced, the CRT will be loaded and bound.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	CrtResource.ResourceInstance	Debug/diagnostic data about a CrtResource object

Constructor Summary

Constructors

Constructor	Description
CrtResource()	Default constructor

Method Summary

Modifier and Type	Method	Description
protected void	acquireNativeHandle(long handle)	Takes ownership of a native object where the native pointer is tracked as a long.
void	addRef()	Increments the reference count to this resource.
void	addReferenceTo(CrtResource resource)	Marks a resource as referenced by this resource.
protected abstract boolean	canReleaseReferencesImmediately()	Override that determines whether a resource releases its dependencies at the same time the native handle is released or if it waits.
void	close()
static void	collectNativeResource(java.util.function.Consumer<CrtResource.ResourceInstance> fn)	Applies a generic diagnostic-gathering functor to all CRTResource objects
static void	collectNativeResources(java.util.function.Consumer<String> fn)	Applies a resource description consuming functor to all CRTResource objects
void	decRef()	Decrements the reference count to this resource.
long	getNativeHandle()	returns the native handle associated with this CRTResource.
String	getResourceLogDescription()	Gets a debug/diagnostic string describing this resource and its reference state
boolean	isNull()	Checks if this resource's native handle is NULL.
static void	logNativeResources()	Debug method to log all of the currently un-closed CRTResource objects.
protected abstract void	releaseNativeHandle()	Required override method that must begin the release process of the acquired native handle
protected void	releaseReferences()	Decrements the ref counts for all resources referenced by this resource.
void	removeReferenceTo(CrtResource resource)	Removes a reference from this resource to another.
void	setDescription(String description)	Sets a custom logging description for this resource
protected void	swapReferenceTo(CrtResource oldReference, CrtResource newReference)	Swaps a reference from one resource to another
static void	waitForNoResources()	Debug/test method to wait for the CRTResource count to drop to zero.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CrtResource

public CrtResource()

Default constructor

Method Detail

addReferenceTo

public void addReferenceTo(CrtResource resource)

Marks a resource as referenced by this resource.

Parameters:

resource - The resource to add a reference to

removeReferenceTo

public void removeReferenceTo(CrtResource resource)

Removes a reference from this resource to another.

Parameters:

resource - The resource to remove a reference to

swapReferenceTo

protected void swapReferenceTo(CrtResource oldReference,
                               CrtResource newReference)

Swaps a reference from one resource to another

Parameters:

oldReference - resource to stop referencing

newReference - resource to start referencing

acquireNativeHandle

protected void acquireNativeHandle(long handle)

Takes ownership of a native object where the native pointer is tracked as a long.

Parameters:

handle - pointer to the native object being acquired

getNativeHandle

public long getNativeHandle()

returns the native handle associated with this CRTResource.

Returns:

native address

addRef

public void addRef()

Increments the reference count to this resource.

releaseNativeHandle

protected abstract void releaseNativeHandle()

Required override method that must begin the release process of the acquired native handle

canReleaseReferencesImmediately

protected abstract boolean canReleaseReferencesImmediately()

Override that determines whether a resource releases its dependencies at the same time the native handle is released or if it waits. Resources with asynchronous shutdown processes should override this with false, and establish a callback from native code that invokes releaseReferences() when the asynchronous shutdown process has completed. See HttpClientConnectionManager for an example.

Returns:

true if this resource releases synchronously, false if this resource performs async shutdown

isNull

public boolean isNull()

Checks if this resource's native handle is NULL. For always-null resources this is always true. For all other resources it means it has already been cleaned up or was not properly constructed.

Returns:

true if no native resource is bound, false otherwise

close

public void close()

Specified by:

close in interface AutoCloseable

decRef

public void decRef()

Decrements the reference count to this resource. If zero is reached, begins (and possibly completes) the resource's cleanup process.

releaseReferences

protected void releaseReferences()

Decrements the ref counts for all resources referenced by this resource. Most resources will have this called from their close() function, but resources with asynchronous shutdown processes must have it called from a shutdown completion callback.

setDescription

public void setDescription(String description)

Sets a custom logging description for this resource

Parameters:

description - custom resource description

getResourceLogDescription

public String getResourceLogDescription()

Gets a debug/diagnostic string describing this resource and its reference state

Returns:

resource diagnostic string

collectNativeResources

public static void collectNativeResources(java.util.function.Consumer<String> fn)

Applies a resource description consuming functor to all CRTResource objects

Parameters:

fn - function to apply to each resource description

collectNativeResource

public static void collectNativeResource(java.util.function.Consumer<CrtResource.ResourceInstance> fn)

Applies a generic diagnostic-gathering functor to all CRTResource objects

Parameters:

fn - function to apply to each outstanding Crt resource

logNativeResources

public static void logNativeResources()

Debug method to log all of the currently un-closed CRTResource objects.

waitForNoResources

public static void waitForNoResources()

Debug/test method to wait for the CRTResource count to drop to zero. Times out with an exception after a period of waiting.