NAME

cru_mutated - overwrite vertices or edges in place on a graph

SYNOPSIS

#include <cru/cru.h>

cru_graph cru_mutated (
   cru_graph g ,
   cru_mutator m ,
   cru_kill_switch k ,
   unsigned lanes ,
   int *err )

DESCRIPTION

This function computes new vertices and edges for a graph g according to user-defined criteria set by m following the usual cru_mutator calling conventions, and then overwrites the existing vertices and edges with them. Alternatively, a NULL value of m is allowed and causes the graph to be returned unmodified.

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, the whole graph is reclaimed.

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, the graph g is consumed and should not be accessed or reclaimed afterwards.

RETURN VALUE

On successful completion, the returned value is a pointer to a graph derived from g by overwriting edges or vertices as specified by the given cru_mutator structure m. Applications should treat the returned value as opaque but may pass it as a parameter to other library functions. In the event of any error, a NULL pointer is returned. A NULL pointer is also returned if the given parameter g is NULL, which in this case represents an empty graph and is not in itself an error.

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

Consistency checks on the cru_mutator m failed.

CRU_INCINV

The field m->mu_plan.zone.offset is non-zero but the vertex m->mu_plan.zone.initial_vertex is not in the graph g.

CRU_TPCMPR

The m_free and r_free fields differ where the vacuous_case field is NULL in any of the m->mu_kernel.v_op.incident, m->mu_kernel.v_op.outgoing, or m->mu_kernel.e_op structures.

CRU_UNDMAP

The map field in any of m->mu_kernel.v_op.incident, m->mu_kernel.v_op.outgoing, or m->mu_kernel.e_op is NULL but at least one other field in it is not NULL.

CRU_UNDRED

The reduction field is NULL in either of m->mu_kernel.v_op.incident or m->mu_kernel.v_op.outgoing whose other fields are not all NULL.

CRU_UNDVAC

The m->mu_kernel.v_op.incident.vacuous_case field is NULL and at least one other field of m->mu_kernel.v_op.incident is not NULL, or the m->mu_kernel.v_op.outgoing.vacuous_case field is NULL and at least one other field of m->mu_kernel.v_op.outgoing is not NULL.

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