NAME

cru_spread - resume building a partially built graph

SYNOPSIS

#include <cru/cru.h>

cru_graph cru_spread (
   cru_graph g ,
   cru_builder b ,
   cru_kill_switch k ,
   unsigned lanes ,
   int *err )

DESCRIPTION

This function enables graphs to be built in multiple passes. When cru_spread is passed an existing graph g previously built by cru_built, these conditions apply.

• Any vertex in g that has any outgoing edges before cru_spread is called acquires no additional outgoing edges.
• Any vertex in g lacking outgoing edges at the time cru_spread is called, and any new vertex created afterwards, is passed to the connector or subconnector function in b following the usual cru_builder calling conventions to create new outgoing edges from it and possibly new adjacent vertices.

The parameter b is required to point to a cru_builder whose bu_sig field contains orders and destructors identical to those of the cru_sig in the cru_builder initially used to build g by cru_built, but whose connector or subconnector functions may differ. The bu_sig.vertex_limit field may also differ.

The value passed through k may be either a cru_kill_switch previously obtained by the cru_new_kill_switch function or a NULL pointer denoted alternatively by UNKILLABLE. If code running in another thread passes the kill switch to cru_kill while the operation is in progress, then the operation is interrupted. In this case, g is reclaimed and a NULL value is returned.

The lanes parameter specifies the number of worker threads to be used for the operation. Higher numbers up to the number of CPU cores on the host are conducive to higher performance.

• A value of 0, denoted alternatively by CONCURRENTLY, requests a number of threads equal to the number of cores.
• A value of 1, denoted alternatively by SEQUENTIALLY, requests single threaded operation.

For purposes of memory management, g is consumed by cru_spread and should not be reclaimed by the caller.

RETURN VALUE

On successful completion, the returned value is a pointer to a graph derived from g by being spread according to the given specification, which applications should treat as opaque but may pass as a parameter to other library functions. In the event of any error, a NULL pointer is returned. An unmodified copy of g is returned if the parameter b is NULL.

ERRORS

The err parameter is used to report any events preventing successful completion of the requested operation to the caller. If *err is zero on entry and the operation does not succeed, then *err is assigned a non-zero number. If the operation does not succeed because a user-defined callback function reports an error, then the number reported by the callback function is assigned to *err. Positive numbers are for POSIX or user-defined error codes, negative numbers down to -CRU_MAX_ERR are specific to cru, and other negative numbers are allowed as user-defined error codes.

Values of *err listed below refer to errors that are detected and handled. Unlisted values in the range of -CRU_INT_ERR through -CRU_MAX_ERR likely indicate internal errors attributable to bugs in cru. Any other unlisted values may indicate memory corruption, invalid usage of the API, or conditions relevant to user-defined callback functions.

ENOMEM

There is insufficient memory to allocate all necessary resources.

EAGAIN

Resources or permissions are insufficient to create a thread.

CRU_BADKIL

The parameter k refers to an invalid or corrupted kill switch structure.

CRU_INTKIL

The operation was stopped by user intervention using the kill switch k.

CRU_UNDCON

Both of the fields b->connector and b->subconnector are NULL.

CRU_INCCON

Both of the fields b->connector and b->subconnector are initialized as something other than NULL.

CRU_INTOVF

The number of vertices approached or exceeded the limit set by b->bu_sig.vertex_limit.

CRU_UNDEQU

A vertex destructor is defined by b->bu_sig.destructors.v_free but no vertex equality relation is defined in b->bu_sig.orders.v_order.equal, or an edge destructor is defined by b->bu_sig.destructors.e_free but no edge equality relation is defined in b->bu_sig.orders.e_order.equal.

CRU_UNDHSH

A vertex destructor is defined by b->bu_sig.destructors.v_free but no vertex hash function is defined in b->bu_sig.orders.v_order.hash or an edge destructor is defined by b->bu_sig.destructors.e_free but no vertex hash function is defined in b->bu_sig.orders.e_order.hash.

CRU_INCSPB

The given orders b->bu_sig.orders or the destructors b->bu_sig.destructors differ from those used in the cru_builder previously passed to cru_built to build the graph g.

NOTES

This function may be useful for saving memory in applications that build a graph and then prune it. When building the whole graph before pruning it is prohibitive, building the graph in phases and pruning it during each phase may be feasible.

FILES

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

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

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

/usr/local/include/cru/function_types.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_postponer, cru_prop, cru_prop_pair, cru_pruner, cru_qop, cru_qpred, cru_set, cru_sig, cru_singleton, cru_split, cru_splitter, 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