records

These records are attached by client programs dynamically at runtime. More...

Collaboration diagram for records:

Files
file	rec.c

Data Structures
struct	Agrec_s
	implementation of Agrec_t More...

Typedefs
typedef struct Agsym_s	Agsym_t
	string attribute descriptors
typedef struct Agattr_s	Agattr_t
	string attribute container
typedef struct Agdatadict_s	Agdatadict_t
	set of dictionaries per graph
typedef struct Agrec_s	Agrec_t
	generic header of Agattr_s, Agdatadict_s and user records

Functions
void *	agbindrec (void *obj, const char *name, unsigned int recsize, int move_to_front)
	attaches a new record of the given size to the object
Agrec_t *	aggetrec (void *obj, const char *name, int move_to_front)
	find record in circular list and do optional move-to-front and lock
int	agdelrec (void *obj, const char *name)
	deletes a named record from one object
void	aginit (Agraph_t *g, int kind, const char *rec_name, int rec_size, int move_to_front)
	attach new records to objects of specified kind
void	agclean (Agraph_t *g, int kind, char *rec_name)
	calls agdelrec for all objects of the same class in an entire graph

Detailed Description

Uninterpreted records may be attached to graphs, subgraphs, nodes, and edges for efficient operations on values such as marks, weights, counts, and pointers needed by algorithms. Application programmers define the fields of these records, but they must be declared with a common record header Agrec_t.

A unique string ID (stored in Agrec_s::name) must be given to each record attached to the same object. Cgraph has functions to create, search for, and delete these records. The records are maintained in a circular list, with Agobj_s::data pointing somewhere in the list. The search function aggetrec has an option to lock this pointer on a given record. The application must be written so only one such lock is outstanding at a time.

Records are created and managed by Libcgraph. A programmer must explicitly attach them to the objects in a graph, either to individual objects one at a time via agbindrec, or to all the objects of the same class in a graph via aginit. The name argument of a record distinguishes various types of records, and is programmer defined.

Libcgraph reserves the prefix "_AG_" (in DataDictName, AgDataRecName, DRName).

Internally, records Agrec_s are maintained in circular linked lists attached to graph objects Agobj_s. To allow referencing application-dependent data without function calls or search, Libcgraph allows setting and locking the list pointer of a graph, node, or edge on a particular record (see Agtag_s::mtflock and Agobj_s::data). This pointer can be obtained with the macro AGDATA(obj). A cast, generally within a macro or inline function, is usually applied to convert the list pointer to an appropriate programmer-defined type (eg. GD_parent).

To control the setting of this pointer, the move_to_front flag may be TRUE or FALSE. If move_to_front is TRUE, the record will be locked Agtag_s::mtflock at the head of the list Agobj_s::data, so it can be accessed directly by AGDATA(obj).

The lock protects the data pointer from being moved. Function aggetrec reports error when data pointer and lock are reassigned.

The lock can be released or reset by a call to agdelrec.

Typedef Documentation

Agattr_t

typedef struct Agattr_s Agattr_t

Definition at line 166 of file cgraph.h.

Agdatadict_t

typedef struct Agdatadict_s Agdatadict_t

Definition at line 167 of file cgraph.h.

Agrec_t

typedef struct Agrec_s Agrec_t

Definition at line 168 of file cgraph.h.

Agsym_t

typedef struct Agsym_s Agsym_t

Definition at line 165 of file cgraph.h.

Function Documentation

agbindrec()

void * agbindrec	(	void *	obj,
		const char *	name,
		unsigned int	recsize,
		int	move_to_front
	)

Parameters

recsize

if 0, the call to agbindrec is simply a lookup

Returns

pointer to Agrec_t and user data

Definition at line 89 of file rec.c.

References aggetrec(), agraphof(), agstrdup(), gv_calloc(), Agrec_s::name, NULL, and objputrec().

Referenced by aginit(), agmakeattrs(), agmakedatadict(), bundle(), cccomps(), ccomps(), checkLabelOrder(), circomps(), circular_init_edge(), clone_graph(), cloneEdge(), cloneEdge(), cloneGraph(), cloneGraph(), cloneNode(), cloneSubg(), cluster_init_graph(), clustNode(), copyCluster(), deriveClusters(), deriveGraph(), deriveGraph(), dfs(), dot2_rank(), dot_cleanup_graph(), dot_init_edge(), dot_init_node(), dot_init_subg(), emitNode(), find_pair_edges(), findCComp(), graphRecord(), gvFreeLayout(), gvLayoutJobs(), init_edge(), initSubg(), make_flat_adj_edges(), makeBlockGraph(), makeDerivedNode(), makeDotGraph(), mapGraphs(), mapN(), mkBlock(), mkClusters(), mkClusters(), mkClusters(), mkConstraintG(), mkDeriveNode(), mkNConstraintG(), my_init_edge(), my_init_graph(), my_init_node(), neato_init_edge(), neato_init_node(), newedge(), newnode(), openEdge(), openG(), openNode(), openSubg(), patchwork_init_edge(), patchwork_init_node_edge(), pccomps(), processClusterEdges(), projectG(), realFillRanks(), sfdp_init_edge(), spanning_tree(), twopi_init_edge(), undoClusterEdges(), and visit().

Here is the call graph for this function:

Here is the caller graph for this function:

agclean()

void agclean	(	Agraph_t *	g,
		int	kind,
		char *	rec_name
	)

Definition at line 202 of file rec.c.

References agapply(), agdelrec(), agfstnode(), agfstout(), AGINEDGE, AGNODE, agnxtnode(), agnxtout(), AGOUTEDGE, AGRAPH, and simple_delrec().

Referenced by cccomps(), graph_cleanup(), gvToolTred(), and post().

Here is the call graph for this function:

Here is the caller graph for this function:

agdelrec()

int agdelrec	(	void *	obj,
		const char *	name
	)

Definition at line 137 of file rec.c.

References agapply(), aggetrec(), AGINEDGE, AGNODE, AGOUTEDGE, AGRAPH, agraphof(), agroot(), agstrfree(), FAILURE, free(), listdelrec(), Agrec_s::name, objdelrec(), Agtag_s::objtype, SUCCESS, Agobj_s::tag, and UNREACHABLE.

Referenced by agclean(), agedgeattr_delete(), agnodeattr_delete(), agraphattr_delete(), dot_cleanup_node(), freeDerivedGraph(), freeDeriveNode(), gv_cleanup_edge(), gv_cleanup_node(), neato_layout(), and simple_delrec().

Here is the call graph for this function:

Here is the caller graph for this function:

aggetrec()

Agrec_t * aggetrec	(	void *	obj,
		const char *	name,
		int	move_to_front
	)

Definition at line 41 of file rec.c.

References agerrorf(), Agobj_s::data, Agtag_s::mtflock, Agrec_s::name, Agrec_s::next, NULL, set_data(), streq(), and Agobj_s::tag.

Referenced by agattrrec(), agbindrec(), agdatadict(), agdelrec(), graphcmd_internal(), mapClust(), openEdge(), openNode(), and openSubg().

Here is the call graph for this function:

Here is the caller graph for this function:

aginit()

void aginit	(	Agraph_t *	g,
		int	kind,
		const char *	rec_name,
		int	rec_size,
		int	move_to_front
	)

Parameters

kind	may be AGRAPH, AGNODE, or AGEDGE
rec_size	if is negative (of the actual rec_size) for graphs, aginit is applied recursively to the graph and its subgraphs

Definition at line 170 of file rec.c.

References agbindrec(), agfstnode(), agfstout(), agfstsubg(), AGINEDGE, aginit(), AGNODE, agnxtnode(), agnxtout(), agnxtsubg(), AGOUTEDGE, and AGRAPH.

Referenced by aginit(), bindGraphinfo(), cccomps(), color(), eval(), fdp_init_node_edge(), graphviz_acyclic(), gv_to_gxl(), gvevent_read(), gvToolTred(), init_graph(), initDotIO(), main(), pre(), process(), process(), process(), processClusters(), readG(), updateSmGraph(), and write_graph().

Here is the call graph for this function:

Here is the caller graph for this function: