Documentation/core-api/assoc_array.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/assoc_array.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/assoc_array.rst
Extension
.rst
Size
21917 bytes
Lines
565
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct assoc_array {
            ...
    };

The code is selected by enabling ``CONFIG_ASSOCIATIVE_ARRAY`` with::

    ./script/config -e ASSOCIATIVE_ARRAY


Edit Script
-----------

The insertion and deletion functions produce an 'edit script' that can later be
applied to effect the changes without risking ``ENOMEM``. This retains the
preallocated metadata blocks that will be installed in the internal tree and
keeps track of the metadata blocks that will be removed from the tree when the
script is applied.

This is also used to keep track of dead blocks and dead objects after the
script has been applied so that they can be freed later.  The freeing is done
after an RCU grace period has passed - thus allowing access functions to
proceed under the RCU read lock.

The script appears as outside of the API as a pointer of the type::

    struct assoc_array_edit;

There are two functions for dealing with the script:

1. Apply an edit script::

    void assoc_array_apply_edit(struct assoc_array_edit *edit);

   This will perform the edit functions, interpolating various write barriers
   to permit accesses under the RCU read lock to continue.  The edit script
   will then be passed to ``call_rcu()`` to free it and any dead stuff it
   points to.

2. Cancel an edit script::

    void assoc_array_cancel_edit(struct assoc_array_edit *edit);

   This frees the edit script and all preallocated memory immediately. If
   this was for insertion, the new object is *not* released by this function,
   but must rather be released by the caller.

These functions are guaranteed not to fail.


Operations Table
----------------

Various functions take a table of operations::

    struct assoc_array_ops {
            ...
    };

This points to a number of methods, all of which need to be provided:

1. Get a chunk of index key from caller data::

    unsigned long (*get_key_chunk)(const void *index_key, int level);

   This should return a chunk of caller-supplied index key starting at the
   *bit* position given by the level argument.  The level argument will be a
   multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return
   ``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``.  No error is possible.

Annotation

Implementation Notes