XtAppReleaseCacheRefs() XtAppReleaseCacheRefs()
Name
XtAppReleaseCacheRefs - decrement the reference counts for cached resources obtained from XtCallConverter().
Synopsis
void XtAppReleaseCacheRefs(app, refs)
XtAppContext app;
XtCacheRef *refs;
Inputs
app Specifies the application context.
refs Specifies a NULL-terminated array of cache references to be decremented.
Availability
Release 4 and later.
Description
XtAppReleaseCacheRefs() decrements the reference count for each XtCacheRef in the NULL-terminated array refs. If any reference count
reaches zero, the destructor registered with XtSetTypeConverter() for that resource type, if any, will be called and the resource removed
from the conversion cache.
An XtCacheRef is a handle to a cached resource value. It is obtained in a call to XtCallConverter().
Usage
Applications and widgets should very rarely need to call this function. The Intrinsics provide two predefined callbacks which can be reg-
istered with an XtCacheRef or an array of XtCacheRef on the destroy callback of a widget or object to automatically call XtAppRelease-
CacheRefs() when the resources are no longer needed. See XtCallbackReleaseCacheRef() and XtCallbackReleaseCacheRefList().
Additionally, the function XtConvertAndStore() which is a higher-level interface to resource converters than XtCallConverter() is passed a
widget or object and automatically registers XtCallbackReleaseCacheRef() on the object's destroy callback if needed. XtCreateWidget() may
also register such callbacks.
Structures
XtCacheRef is an opaque type.
See AlsoXtCallbackReleaseCacheRef(1), XtCallbackReleaseCacheRefList(1), XtCallConverter(1), XtConvertAndStore(1), XtSetTypeConverter(1),
XtDestructor(2).
Xt - Resource Management XtAppReleaseCacheRefs()
Check Out this Related Man Page
XtCallConverter() XtCallConverter()
Name
XtCallConverter - explicitly invoke a "new-style" resource converter and cache result.
Synopsis
Boolean XtCallConverter(display, converter, args, num_args, from, to_in_out, cache_ref_return)
Display* display;
XtTypeConverter converter;
XrmValuePtr args;
Cardinal num_args;
XrmValuePtr from;
XrmValuePtr to_in_out;
XtCacheRef *cache_ref_return;
Inputs
display Specifies the display with which the conversion is to be associated.
converter Specifies the new-style conversion procedure to be called.
args Specifies the additional conversion arguments needed to perform the conversion, or NULL.
num_args Specifies the number of additional arguments.
from Specifies the source value to be converted.
to_in_out Specifies the address at which the converted value is to be stored, and the number of bytes allocated at that address.
Outputs
to_in_out Returns (in the size field) the actual size of the converted value.
cache_ref_return
Returns a conversion cache ID if the converter was registered with reference counting. NULL may be passed for this argument if
the caller is not interested in reference counting of cached conversion values.
Returns
True if the conversion was performed successfully, False otherwise.
Availability
Release 4 and later.
Description
XtCallConverter() converts the value from as appropriate for the conversion procedure converter by looking a converted value up in the
cache, or by invoking the converter with the display, args, num_args, from, and to_in_out arguments.
to_in_out->addr should contain the address at which the converted value is to be stored, and to_in_out->size should contain the number of
bytes allocated at that address.
See the "Background" section below for more details.
Usage
XtConvertAndStore() is a higher level interface to resource conversion, and is easier to use in most cases.
You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics
resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you
need to invoke another converter.
If XtCallConverter() returns an XtCacheRef value you must store it and decrement the reference count (with XtAppReleaseCacheRefs()) when
you no longer need the converted value. The easiest way to do this is to register the predefined callback XtCallbackReleaseCacheRef() on
the destroy callback of the widget or object that is using the converted value.
Background
XtCallConverter() looks up the specified type converter in the application context associated with the display. If the converter was not
registered or was registered with cache type XtCacheAll or XtCacheByDisplay, XtCallConverter() looks in the conversion cache to see whether
this conversion procedure has been called with the specified arguments. If so, XtCallConverter() checks the success status of the prior
call. If the conversion failed, XtCallConverter() returns False immediately; otherwise it checks the size specified in the to_in_out argu-
ment.
If this size is greater than or equal to the size stored in the cache, XtCallConverter():
o Copies the information stored in the cache to the location specified by the to_in_out argument.
o Stores the cache size in to_in_out->size.
o Returns True.
If the size specified in the to_in_out argument is smaller than the size stored in the cache, XtCallConverter() copies the cache size into
to->size and returns False. If the converter was registered with cache type XtCacheNone or if no value was found in the conversion cache,
XtCallConverter() calls the converter and, if it was not registered with cache type XtCacheNone, enters the result in the cache. XtCall-
Converter() then returns what the converter returned.
cache_ref_return specifies storage allocated by the caller in which an opaque value will be stored. If the type converter has been regis-
tered with the XtCacheRefCount modifier and if the value returned in cache_ref_return is non-NULL, then the caller should store the
cache_ref_return value in order to decrement the reference count when the converted value is no longer required. cache_ref_return should
be specified as NULL if the caller is unwilling or unable to store the value.
Structures
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
See AlsoXtCallbackReleaseCacheRef(1), XtConvertAndStore(1), XtSetTypeConverter(1),
XtTypeConverter(2).
Xt - Resource Management XtCallConverter()