From GridLAB-D Wiki
Jump to: navigation, search

gld_objlist - Advanced object list handling class

Synopsis

class gld_objlist {
private:
	struct s_objlist *list;
public:
	inline operator OBJLIST*();
public:
	inline gld_objlist(void);
	inline gld_objlist_objlist(CLASS *c, PROPERTY *m, char *p, char *o, void *a, void *b=NULL);
	inline gld_objlist_objlist(char *cn, char *mn, char *p, char *o, void *a, void *b=NULL);
	inline ~gld_objlist_objlist(void);
public:
	inline size_t add(PROPERTY *m, char *p, char *o, void *a, void *b=NULL);
	inline size_t del(PROPERTY *m, char *p, char *o, void *a, void *b=NULL);
	inline size_t add(char *cn, char *mn, char *p, char *o, void *a, void *b=NULL);
	inline size_t del(char *cn, char *mn, char *p, char *o, void *a, void *b=NULL);
public:
	inline bool is_valid(void);
	inline size_t get_size(void);
	inline OBJECT *get(size_t n);
	inline int apply(void *arg, int (*function)(OBJECT *,void*,int));
	inline void exception(char *msg, ...);
};

Description

The advanced object list handling routine provide a mechanism to create a list of objects that match a particular criteria, to scan through the list, and to apply a function to the list.

gld_objlist

inline gld_objlist(void)
inline gld_objlist(CLASS *oclass, PROPERTY *match, char *part, char *op, void *aval, void *bval=NULL)
inline gld_objlist(char *classname, char *match_name, char *part, char *op, void *aval, void *bval=NULL)
inline ~gld_objlist(void)
The constructors accept either a class/property entities or class/property names. The part, operator, a and b values are provided in a manner similar to gld_property::compare(). Note that the a and b values must be pointers to the data and not the data itself.

add

inline size_t add(PROPERTY *m, char *p, char *o, void *a, void *b=NULL)
inline size_t add(char *cn, char *mn, char *p, char *o, void *a, void *b=NULL)
Adds objects to the list that match the criteria given. The part, operator, a and b values are provided in a manner similar to gld_property::compare(). Note that the a and b values must be pointers to the data and not the data itself.

del

inline size_t del(PROPERTY *m, char *p, char *o, void *a, void *b=NULL)
inline size_t del(char *cn, char *mn, char *p, char *o, void *a, void *b=NULL)
Deletes objects from the list that match the criteria. The part, operator, a and b values are provided in a manner similar to gld_property::compare(). Note that the a and b values must be pointers to the data and not the data itself.

is_valid

bool is_valid(void)
Returns true if the object list is valid and false if it is not valid.

get_size

size_t get_size(void)
Returns the number of objects in the list.

get

OBJECT *get(size_t n)
Returns a pointer to the nth object in the list.

apply

inline int apply(void *arg, int (*function)(OBJECT *,void*,int));
Applies the function to each item in the list. The definition of arg is function specific and determined by the programmer. The function expects the first argument to be a pointer to the object, the second a pointer to the arg structure, and the third to be the object position in the list.
The function is called the first time with a pointer to the first object and the index zero, which can be used to perform any needed pre-processing on arg.
The function will be called once with a NULL object pointer and -1 are the index to indicate that no further calls will be performed and the function can perform any post-processing needed on arg.
The function must return the number of items processed. If a failure occurs, the return value must be negative and the magnitude of the negative number indicates how many objects were successfully processed before the failure. Zero indicates no objects were processed, which indicates a failure on the first object only if the list contains more than zero objects.

Example

The following example creates a list of object and applies a mean calculate to that list.

struct s_arg {
	size_t addr;    // object property addr of value used by logmean 
	double sum;     // accumulator for sum
	unsigned int n; // accumulator for count
	double ans;     // storage for answer	
};
int mean(OBJECT *obj,void *arg,int n)
{
	struct s_arg *res = (struct s_arg*)arg;
	if ( obj ) // normal call
	{
		double x = *(double*)((char*)(obj+1)+(int64)res->addr);
		res->sum += x;
		res->n++;
	} // last call
	else
	{
		res->ans = res->sum / res->n;
	}
	return 1;
}
int example(void)
{
	gl_error("mysql::collector is not supported yet");

	double zero=0.0, pos=+3.0, neg=-pos;
	clock_t start = clock();
	gld_objlist list("example","x",NULL,"inside",&neg,&pos);
	gl_verbose("%d objects found", list.get_size());
	clock_t mid = clock();
	struct s_arg arg = {0,0.0,00.0};
	gl_verbose("result=%d, mean=%f", list.apply(&arg,mean),arg.ans);
	clock_t done = clock();

	gl_verbose("create time=%.3fms, apply time=%.3fms", (mid-start)*1.0e3/CLOCKS_PER_SEC,(done-mid)*1.0e3/CLOCKS_PER_SEC);
	return 1;
}

Version

The C++ Module API was introduced in Hassayampa (Version 3.0) to ensure support for multithreading.

See also