PMADELTAINDOM(3)

NAME
pmaDeltaInDom - generate a ``delta indom'' if two observations of an instance domain are different

C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/libpcp.h>
#include <pcp/archive.h>

void pmaDeltaInDom(__pmLogInDom *old, __pmLogInDom *new, __pmLogInDom *new_delta);

cc ... -lpcp_archive -lpcp

CAVEAT
This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future.

DESCRIPTION
Checks if two observations of the same instance domain are identical, and if they are not, tries to generate a ``delta indom'' to describe the differences.

The code assumes (a) old->indom == new->indom and (b) both the instance domains are sorted in ascending internal instance identifier sequence; see pmaSortInDom(3) to see how to make the second condition true.

The ``delta indom'' format is only supported for Version 3 archives and it is the caller's responsibility to determine if calling pmaDeltaInDom is appropriate, rather than calling pmaSameInDom(3) which is the preferred method for V2 archives.

pmaDeltaInDom returns 0 if the old and new instance domains are the same.

A return value of 1 indicates that the instance domains are different and the ``delta indom'' format is not more efficient; in this case new_delta is not modified.

A return value of 2 indicates that the instance domains are different and new_delta has been set up to describe the ``delta indom'' encoding of the differences; in this case the caller is responsible for freeing new_delta->instlist and new_delta->namelist.

The instance domains are considered different if any of the following hold:

1.  old->numinst != new->numinst

2.  For some i, old->instlist[i] != new->instlist[i]

3.  For some i, the strings pointed to by old->namelist[i] and new->instlist[i] are not identical

DELTA INDOM FORMAT
As for a regular instance domain, new_delta->numinst defines the number of instance specifications.

If new_delta->namelist[i] == NULL then the instance identified by new_delta->instlist[i] has been deleted from the instance domain.

If new_delta->namelist[i] != NULL then the instance identified by new_delta->instlist[i] has been added to the instance domain.

Because the ``delta indom'' is only likely to have short-term relevance to the caller, the new_delta->namelist[i] entries that are not NULL will point back into old->namelist[j] or new->namelist[k] and so old and new should not be freed until the caller has finished with new_delta.

SEE ALSO
PMAPI(3), pmaSortInDom(3) and pmaSameInDom(3).