Data change tracking

Overview

// typedefs

typedef te_errno tapi_cfg_changed_callback(
    const char *tag,
    size_t start,
    size_t len,
    void *ctx
    );

// global functions

te_errno tapi_cfg_changed_add_region(const char* tag, size_t start, size_t len);
te_errno tapi_cfg_changed_add_region_overlap(const char* tag, size_t start, size_t len);
te_errno tapi_cfg_changed_remove_region(const char* tag, size_t start);
te_errno tapi_cfg_changed_remove_region_overlap(const char* tag, size_t start, size_t len);
te_errno tapi_cfg_changed_process_regions(const char* tag, tapi_cfg_changed_callback* cb, void* ctx);
te_errno tapi_cfg_changed_clear_tag(const char* tag);

Detailed Documentation

Typedefs

typedef te_errno tapi_cfg_changed_callback(
    const char *tag,
    size_t start,
    size_t len,
    void *ctx
    )

Type for tapi_cfg_changed_process_regions() callback functions.

Parameters:

tag	Change scope identifier
start	Start of a region
len	Length of a region
ctx	User data
0	tapi_cfg_changed_process_regions() would remove the processed region
TE_EGAIN	the region would be retained

Returns:

Status code

Global Functions

te_errno tapi_cfg_changed_add_region(const char* tag, size_t start, size_t len)

Add a changed region starting at start of the length len. If there’s already a marked region at this point, its length is extended (but never shrunk). No other checks are done, so this function may cause overlapping regions to appear.

The semantics of region is completely test-specific, they may be blocks, pages byte ranges or anything else.

Parameters:

tag	Change scope identifier (i.e. a block device name)
start	Start of a region
len	Length of a region

Returns:

Status code

te_errno tapi_cfg_changed_add_region_overlap(const char* tag, size_t start, size_t len)

Like tapi_cfg_changed_add_region(), but properly check for overlapping regions and modify them accordingly.

This function is more robust than tapi_cfg_changed_add_region() but is significantly slower because a full list of regions under a given tag should be retrieved. Basically it performs a union of already marked regions and an interval start.. start + len.

Parameters:

tag	Change scope identifier
start	Start of a region
len	Length of a region

Returns:

Status code

te_errno tapi_cfg_changed_remove_region(const char* tag, size_t start)

Remove a changed region of any length that starts at start.

If there is no region at start, the function does nothing. The region must start exactly at start, no checks for overlapping regions are performed.

Parameters:

tag	Change scope identifier
start	Start of a region

Returns:

Status code

te_errno tapi_cfg_changed_remove_region_overlap(const char* tag, size_t start, size_t len)

Exclude start.. start + length from a list of changed regions.

Unlike tapi_cfg_changed_remove_region(), the function performs proper set difference. In particular that may mean that a single region may be split in two.

Parameters:

tag	Change scope identifier
start	Start of a region
len	Length of a region

Returns:

Status code

te_errno tapi_cfg_changed_process_regions(const char* tag, tapi_cfg_changed_callback* cb, void* ctx)

Process all defined regions for a given tag calling cb on each of them.

The regions are processed in the increased order of their start points. The function fixes possible unsigned overflows (e.g. if a length is SIZE_MAX) and adjust the lengths to removed overlaps, so the callback may see a different length of a region than stored in the Configurator tree.

If the callback returns 0, the current region is removed. If the callback return TE_EAGAIN, the region is retained. All other return values cause processing to stop immediately.

Parameters:

tag	Change scope identifier
cb	Callback
ctx	User data

Returns:

Status code

te_errno tapi_cfg_changed_clear_tag(const char* tag)

Remove all changed regions belonging to a given tag.

Parameters:

tag	Change scope identifier

Returns:

Status code