NAME

cru_postponer - specification for selectively serializing edges

SYNOPSIS

#include <cru/cru.h>

typedef struct cru_postponer_s
{
   int po_fix;
   cru_tpred postponable;
   struct cru_cbop_s postponement;
} *cru_postponer;

DESCRIPTION

This structure parameterizes the cru_postponed library function with necessary information initialized by the application to transplant some of the edges in a graph to the termini of their sibling edges with possible modifications.

Each edge in a given graph is tested for being postponable according to user-defined criteria by the ternary predicate referenced through the postponable field. Given the edge's origin as its left operand, the edge's label as its middle operand, and the edge's terminus as its right operand, the predicate is expected to return a non-zero value only for the postponable edges. From that point, the computation proceeds as follows.

• For each vertex from which some but not all outgoing edges are postponable, the set of all pairs of its outgoing edges is constructed containing one postponable edge and one not.
• For each pair of edges thus constructed, the binary predicate referenced through the postponement.bpred field is used to test the pair of their labels, with the label from the postponable edge as its left operand.
• If the binary predicate returns zero, there is no effect on the graph. If it returns any non-zero value, then the postponable edge is deleted from the graph and the same operands in the same order are passed to the binary operator referenced through the postponement.bop field. The binary operator is expected to return the label of a new edge to be included in the graph.
• For each edge label thus obtained, a new edge having that label is made to terminate at the former terminus of the deleted postponable edge in the pair, and to originate from the terminus of the other edge.

For these purposes, edges that originate and terminate at the same vertex are ignored. Two further options are available.

• If the po_fix field is non-zero, then the operations above are iterated until the graph is unchanged between consecutive iterations.
• If the postponement.bpred field is omitted or NULL, then the postponable edge is deleted unconditionally and the binary operator is invoked unconditionally.

ERRORS

If the postponable field is omitted or NULL, then the cru_postponed function reports an error of CRU_UNDPOP for an undefined postponable predicate.

It is an error for the binary operator to create edge labels of a type that can not be reclaimed by the same destructor as those already present in the graph. This error is not detected but will cause memory leaks or worse.

FILES

/usr/local/include/cru/data_types.h

/usr/local/include/cru/error_codes.h

SEE ALSO

cru, cru_bop, cru_bpred, cru_builder, cru_built, cru_cbop, cru_classifier, cru_class_of, cru_class_size, cru_composed, cru_composer, cru_connect, cru_connector, cru_cqop, cru_crossed, cru_crosser, cru_ctop, cru_ctop_pair, cru_ctop_quad, cru_data_types, cru_deduplicated, cru_destructor, cru_destructor_pair, cru_edge_count, cru_fabricated, cru_fabricator, cru_filter, cru_filtered, cru_fold, cru_free_kill_switch, cru_free_later, cru_free_now, cru_free_partition, cru_function_types, cru_get, cru_hash, cru_induced, cru_inducer, cru_kernel, cru_kill, cru_killed, cru_mapreduced, cru_mapreducer, cru_merged, cru_merger, cru_mutated, cru_mutator, cru_new_kill_switch, cru_nop, cru_order, cru_order_pair, cru_partition_of, cru_plan, cru_postponed, cru_prop, cru_prop_pair, cru_pruner, cru_qop, cru_qpred, cru_set, cru_sig, cru_singleton, cru_split, cru_splitter, cru_spread, cru_strerror, cru_stretch, cru_stretched, cru_stretcher, cru_subconnector, cru_terminus_count, cru_top, cru_tpred, cru_united, cru_uop, cru_vertex_count, cru_zone

AUTHOR

Dennis Furey (milonga@delayinsensitive.com)

PROJECT PAGE

https://github.com/gueststar/cru