misc.h

GNU Common C++ is a very portable and highly optimized class framework for writing C++ applications

	static int count;
	static int sequence;

	int link;

	Keysym *keys[KEYDATA_INDEX_SIZE];

	/**
	 * Compute a hash key signature id for a symbol name.
	 *
	 * @return key signature index path.
	 * @param sym symbol name.
	 */
	unsigned getIndex(const char *sym);

protected:
	Keysym* getSymbol(const char *sym, bool create);

public:
	/**
	 * Load additional key values into the currrent object from
	 * the specfied config source (a config file/section pair).
	 * These values will overlay the current keywords when matches
	 * are found.  This can be used typically in a derived config
	 * object class constructor to first load a <code>/etc</code> section, and
	 * then load a matching user specific entry from <code>~/.</code> to override
	 * default system values with user specific keyword values.
	 *
	 * @param keypath (filepath/section)
	 */ 
	void load(const char *keypath);

	/**
	 * Load additional key values into the currrent object from
	 * the specfied config source (a config file/section pair).
	 * These values will overlay the current keywords when matches
	 * are found.  This can be used typically in a derived config
	 * object class constructor to first load a <code>/etc</code> section, and
	 * then load a matching user specific entry from <code>~/.</code> to override
	 * default system values with user specific keyword values.
	 * This varient puts a prefix in front of the key name.
	 *
	 * @param prefix
	 * @param keypath (filepath/section)
	 */ 
	void loadPrefix(const char *prefix, const char *keypath);

	/**
	 * Load additional keys into the current object using a real
	 * filename that is directly passed rather than a computed key
	 * path.  This also uses a [keys] section as passed to the object.
	 *
	 * @param filepath to load from
	 * @param keys section to parse from, or NULL to parse from head
	 * @param pre optional key prefix
	 */
	void loadFile(const char *filepath, const char *keys = NULL, const char *pre = NULL);

	/**
	 * Load default keywords into the current object.  This only
	 * loads keyword entries which have not already been defined
	 * to reduce memory usage.  This form of Load is also commonly
	 * used in the constructor of a derived Keydata class.
	 *
	 * @param pairs list of NULL terminated default keyword/value pairs.
	 */
	void load(Define *pairs);
	
	/**
	 * Create an empty key data object.
	 */
	Keydata();

	/**
	 * Create a new key data object and use "Load" method to load an
	 * initial config file section into it.
	 *
	 * @param keypath (filepath/section)
	 * specifies the home path.
	 */
	Keydata(const char *keypath);

	/**
	 * Alternate constructor can take a define list and an optional
	 * pathfile to parse.
	 *
	 * @param pairs of keyword values from a define list
	 * @param keypath of optional file and section to load from 
	 */
	Keydata(Define *pairs, const char *keypath = NULL);

	/**
	 * Destroy the keydata object and all allocated memory.  This
	 * may also clear the "cache" file stream if no other keydata
	 * objects currently reference it.
	 */
	virtual ~Keydata();

	/**
	 * Unlink the keydata object from the cache file stream.  This
	 * should be used if you plan to keepa Keydata object after it
	 * is loaded once all keydata objects have been loaded, otherwise
	 * the cfgFile stream will remain open.  You can also use
	 * endKeydata().
	 */
	void unlink(void);

	/**
	 * Get a count of the number of data "values" that is associated
	 * with a specific keyword.  Each value is from an accumulation of
	 * "<code>load()</code>" requests.
	 *
	 * @param sym keyword symbol name.
	 * @return count of values associated with keyword.
	 */
	int getCount(const char *sym);

	/**
	 * Get the first data value for a given keyword.  This will
	 * typically be the <code>/etc</code> set global default.
	 *
	 * @param sym keyword symbol name.
	 * @return first set value for this symbol.
	 */
	const char* getFirst(const char *sym);

	/**
	 * Get the last (most recently set) value for a given keyword.
	 * This is typically the value actually used.
	 *
	 * @param sym keywork symbol name.
	 * @return last set value for this symbol.
	 */
	const char* getLast(const char *sym);

	/**
	 * Get an index array of ALL keywords that are stored by the
	 * current keydata object.
	 *
	 * @return number of keywords found.
	 * @param data pointer of array to hold keyword strings.
	 * @param max number of entries the array can hold.
	 */
	unsigned getIndex(char **data, unsigned max);

	/**
	 * Get the count of keyword indexes that are actually available
	 * so one can allocate a table to receive getIndex.
	 *
	 * @return number of keywords found.
	 */
	unsigned getCount(void);

	/**
	 * Set (replace) the value of a given keyword.  This new value
	 * will become the value returned from getLast(), while the
	 * prior value will still be stored and found from <code>getList()</code>.
	 *
	 * @param sym keyword name to set.
	 * @param data string to store for the keyword.
	 */
	void setValue(const char *sym, const char *data);

	/**
	 * Return a list of all values set for the given keyword
	 * returned in order.
	 *
	 * @return list pointer of array holding all keyword values.
	 * @param sym keyword name to fetch.
	 */
	const char * const* getList(const char *sym);

	/**
	 * Clear all values associated with a given keyword.  This does
	 * not de-allocate the keyword from memory, however.
	 *
	 * @return keyword name to clear.
	 */
	void clrValue(const char *sym);

	/**
	 * A convient notation for accessing the keydata as an associative
	 * array of keyword/value pairs through the [] operator.
	 */
	inline const char *operator[](const char *keyword)
		{return getLast(keyword);};

	/**
	 * static member to end keydata i/o allocations.
	 */
	static void end(void);

	/**
	 * Shutdown the file stream cache.  This should be used before
	 * detaching a deamon, <code>exec()</code>, <code>fork()</code>, etc.
	 */
	friend inline void endKeydata(void)
		{Keydata::end();};
};

/**
 * This class is used to create derived classes which are constructed
 * within a memory pager pool.  
 *
 * @short create objects in a memory pager.
 * @author David Sugar <[e-mail]>
 */
class __EXPORT MemPagerObject
{
public:
	/**
	 * Allocate memory from a memory pager.
	 *
	 * @param size of new passed from operator.
	 * @param pager to allocate from.
	 */
	inline void *operator new(size_t size, MemPager &pager)
		{return pager.alloc(size);};

	/**
	 * Allocate array from a memory pager.
	 *
	 * @param size of new passed from operator.
	 * @param pager to allocate from.
	 */
	inline void *operator new[](size_t size, MemPager &pager)
		{return pager.alloc(size);};

	/**
	 * Mempager delete does nothing; the pool purges.
	 */
	inline void operator delete(void *) {};

	/**
	 * Array mempager delete does nothing; the pool purges.
	 */
	inline void operator delete[](void *) {};
};

/**
 * This class is used to associate (object) pointers with named strings.
 * A virtual is used to allocate memory which can be overriden in the
 * derived class.
 *
 * @author David Sugar <[e-mail]>
 * @short associate names with pointers.
 */
class __EXPORT Assoc
{
private:
	class __EXPORT entry
	{
	public:
		const char *id;
		entry *next;
		void *data;
	};

	entry *entries[KEYDATA_INDEX_SIZE];

protected:
	Assoc();
	virtual ~Assoc();

	void clear(void);

	virtual void *getMemory(size_t size) = 0;

public:
	void *getPointer(const char *id);
	void setPointer(const char *id, void *data);
};

/**
 * A runlist is used to restrict concurrent exection to a limited set
 * of concurrent sessions, much like a semaphore.  However, the runlist
 * differs in that it notifies objects when they become ready to run,
 * rather than requiring them to wait and "block" for the semaphore
 * count to become low enough to continue.
 *
 * @author David Sugar <[e-mail]>
 * @short list of runable objects.
 */
class __EXPORT Runlist : public Mutex
{
private:
	Runable *first, *last;

protected:
	unsigned limit, used;
	void check(void);

public:
	/**
	 * Create a new runlist with a specified limit.
	 *
	 * @param count limit before wait queuing.
	 */
	Runlist(unsigned count = 1);
	
	/**
	 * Add a runable object to this runlist.  If the number of
	 * entries running is below the limit, then add returns true
	 * otherwise the entry is added to the list.
	 *
	 * @return true if immediately ready to run
	 * @param run pointer to runable object.
	 */
	bool add(Runable *run);

	/**
	 * Remove a runable object from the wait list or notify when
	 * it is done running so that the used count can be decremented.
	 *
	 * @param run pointer to runable object.
	 */
	void del(Runable *run);

	/**
	 * Set the limit.
	 *
	 * @param limit to use.
	 */
	void set(unsigned limit);
};

/**
 * A container for objects that can be queued against a runlist.
 *
 * @author David Sugar <[e-mail]>
 * @short runable object with notify when ready.
 */
class __EXPORT Runable
{
private:
	friend class __EXPORT Runlist;
	Runlist *list;
	Runable *next, *prev;

protected:
	Runable();
	virtual ~Runable();

	/**
	 * Method handler that is invoked when a wait-listed object
	 * becomes ready to run.
	 */
	virtual void ready(void) = 0;

public:
	/** 
	 * Start the object against a run list.
	 *
	 * @return true if immediately available to run.
	 * @param list to start under.
	 */
	bool starting(Runlist *list);
	
	/**
	 * Stop the object, called when stopping or ready completes.
	 * May also be used for a task that has not yet started to
	 * remove it from the wait list.
	 */
	void stoping(void);
};

#ifdef	CCXX_NAMESPACES
}
#endif

#endif

/** EMACS **
 * Local variables:
 * mode: c++
 * c-basic-offset: 8
 * End:
 */