NAME

cru_partition_of - partition the vertices in a graph

SYNOPSIS

#include <cru/cru.h>

cru_partition cru_partition_of (
   cru_graph g ,
   cru_classifier c ,
   cru_kill_switch k ,
   unsigned lanes ,
   int *err )

DESCRIPTION

This function is part of a simple and efficient API for manipulating sets of vertices in a graph. The parameter g is graph to be partitioned according to the specification given by c, both previously built or initialized by the caller.

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, no partition is constructed.

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.

RETURN VALUE

On successful completion, the function returns a cru_partition representing a partition on the vertices in the graph g, which is a set of classes of vertices such that each vertex belongs to exactly one class. The partition is represented as a pointer that may be used as a parameter to other cru library functions. Otherwise, a NULL pointer is returned.

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 acquire a lock.

CRU_BADGPH

The parameter g refers to an invalid or corrupted graph.

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_NULCSF

A NULL value was passed for the parameter c instead of a pointer to a cru_classifier.

CRU_TPCMPR

The field c->cl_prop.incident.m_free differs from c->cl_prop.incident.r_free when c->cl_prop.incident.vacuous_case is NULL, or the analogous condition holds for c->cl_prop.outgoing.

CRU_UNDEQU

The field c->cl_order.equal is NULL when c->cl_prop.vertex.m_free is not NULL.

CRU_UNDHSH

The field c->cl_order.hash is NULL when c->cl_prop.vertex.m_free is not NULL.

CRU_UNDMAP

The field c->cl_prop.vertex.map is NULL, or either of c->cl_prop.incident.map or c->cl_prop.outgoing.map is NULL when not all other fields of c->cl_prop.incident or c->cl_prop.outgoing respectively are NULL.

CRU_UNDRED

Either of c->cl_prop.incident.reduction or c->cl_prop.outgoing.reduction is NULL when not all other fields of c->cl_prop.incident or c->cl_prop.outgoing respectively are NULL

CRU_UNDVAC

Either of c->cl_prop.incident.vacuous_case or c->cl_prop.outgoing.vacuous_case is NULL when not all other fields of c->cl_prop.incident or c->cl_prop.outgoing respectively are NULL, and there is a vertex in the graph with respectively no incoming or no outgoing edges.

NOTES

Only the vertex map is needed in the classifier c, so the vacuous case and reductions can initialized as NULL. However, if they are defined, then they and their destructors must be consistently typed. Neither of the incident or outgoing folds is needed unless the class property of a vertex depends on its adjacent vertices or edges.

FILES

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

/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_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_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