Dictionary Object API

A dictionary object is a collection of key-value pairs, where both the key and the value are represented by shareable string objects. A shareable string is a data structure that encapsulates a string so that it can't be modified directly. This is to allow multiple processes to read the string without the risk that the string will be changed inadvertently between reads. Modifying a shareable string actually destroys it and creates a new one.

The dictionary object API allows the creation of multiple handles to a dictionary object that can be used and destroyed by independent components of a program. Since a dictionary, once created, is immutable until destroyed, components can access it through their handles without worrying about synchronization.

Different dictionary object handles may be represented by identical pointers. You should not compare handles. Regardless of how the handles are represented internally, you have to call strm_dict_destroy() separately for each handle to properly dispose of any resources associated with it.

This chapter describes the publicly visible dictionary object API functions and data types.

The dictionary object API header file, strm.h, can be found in the folder \usr\include\sys.