src/common/ResourceManager.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __RESOURCE_MANAGER__
#define __RESOURCE_MANAGER__

#include <set>
#include <map>

/**
 * Interface class for consumer classes which use a resource managed
 * by the ResourceManager class.
 */
template<class T_res>
class ResourceConsumer {
    public:
        /**
         * Will be called by the ResourceManager to inform the
         * consumer that a resource currently used by him is going
         * to be updated. The consumer can then react by stopping
         * usage until resource is updated. The ResourceManager will
         * not update the resource until this method returns. This
         * method needs to be implemented by the consumer.
         *
         * @param pResource  - resource going to be updated
         * @param pUpdateArg - pointer the consumer might use to store
         *                     informations he might need when update
         *                     process was completed
         */
        virtual void ResourceToBeUpdated(T_res* pResource, void*& pUpdateArg) = 0;

        /**
         * Will be called by the ResourceManager to inform the
         * consumer that resource update was completed. This method
         * needs to be implemented by the consumer.
         *
         * @param pOldResource - (now invalid) pointer to the old
         *                       resource
         * @param pNewResource - (valid) pointer to the updated
         *                       resource
         * @param pUpdateArg   - pointer the consumer might have used when
         *                       ResourceToBeUpdated() was called
         */
        virtual void ResourceUpdated(T_res* pOldResource, T_res* pNewResource, void* pUpdateArg) = 0;
};

/**
 * Abstract base class for sharing resources between multiple consumers.
 * A consumer can borrow a resource from the ResourceManager, if the
 * resource doesn't exist yet it will be created. Other consumers will
 * just be given the same pointer to the resource then. When all consumers
 * gave back their pointer to the resource, the resource will be destroyed.
 * Descendants of this base class have to implement the (protected)
 * Create() and Destroy() methods to create and destroy a resource.
 */
template<class T_key, class T_res>
class ResourceManager {
    private:
        typedef std::set<ResourceConsumer<T_res>*> ConsumerSet;
        struct resource_entry_t {
            T_key       key;
            T_res*      resource;  ///< pointer to the resource
            ConsumerSet consumers; ///< list of all consumers who currently use the resource
            void*       arg;       ///< optional pointer the descendant might use to store informations about the resource
        };
        typedef std::map<T_key, resource_entry_t> ResourceMap;
        ResourceMap ResourceEntries;

    public:
                virtual ~ResourceManager() {}
        /**
         * Borrow a resource identified by \a Key. The ResourceManager will
         * mark the resource as in usage by the consumer given with
         * \a pConsumer. If the Resource doesn't exist yet it will be
         * created.
         *
         * @param Key       - resource identifier
         * @param pConsumer - identifier of the consumer who borrows it
         * @returns  pointer to resource
         */
        T_res* Borrow(T_key Key, ResourceConsumer<T_res>* pConsumer) {
            typename ResourceMap::iterator iterEntry = ResourceEntries.find(Key);
            if (iterEntry == ResourceEntries.end()) {
                resource_entry_t entry;
                entry.key      = Key;
                entry.resource = Create(Key, pConsumer, entry.arg);
                entry.consumers.insert(pConsumer);
                OnBorrow(entry.resource, pConsumer, entry.arg);
                ResourceEntries[Key] = entry;
                return entry.resource;
            }
            resource_entry_t& entry = iterEntry->second;
            entry.consumers.insert(pConsumer);
            OnBorrow(entry.resource, pConsumer, entry.arg);
            return entry.resource;
        }

        /**
         * Give back a resource. This tells the ResourceManager that the
         * consumer given by \a pConsumer doesn't need the resource anymore.
         * If the resource is not needed by any consumer anymore then the
         * resource will be destroyed.
         *
         * @param pResource - pointer to resource
         * @param pConsumer - identifier of the consumer who borrowed the
         *                    resource
         */
        void HandBack(T_res* pResource, ResourceConsumer<T_res>* pConsumer) {
            typename ResourceMap::iterator iter = ResourceEntries.begin();
            typename ResourceMap::iterator end  = ResourceEntries.end();
            for (; iter != end; iter++) {
                if (iter->second.resource == pResource) {
                    resource_entry_t& entry = iter->second;
                    entry.consumers.erase(pConsumer);
                    if (entry.consumers.empty()) {
                        ResourceEntries.erase(iter);
                        Destroy(entry.resource, entry.arg);
                    }
                    return;
                }
            }
        }

        /**
         * Request update of a resource.
         *
         * @param pResource - resource to be updated
         * @param pConsumer - consumer who requested the update
         */
        void Update(T_res* pResource, ResourceConsumer<T_res>* pConsumer) {
            typename ResourceMap::iterator iter = ResourceEntries.begin();
            typename ResourceMap::iterator end  = ResourceEntries.end();
            for (; iter != end; iter++) {
                if (iter->second.resource == pResource) {
                    resource_entry_t& entry = iter->second;
                    // inform all consumers about pending update
                    std::map<ResourceConsumer<T_res>*,void*> updateargs;
                    typename ConsumerSet::iterator iterCons = entry.consumers.begin();
                    typename ConsumerSet::iterator endCons  = entry.consumers.end();
                    for (; iterCons != endCons; iterCons++) {
                        if (*iterCons == pConsumer) continue;
                        void* updatearg = NULL;
                        (*iterCons)->ResourceToBeUpdated(entry.resource, updatearg);
                        if (updatearg) updateargs[*iterCons] = updatearg;
                    }
                    // update resource
                    T_res* pOldResource = entry.resource;
                    Destroy(entry.resource, entry.arg);
                    entry.resource = Create(entry.key, pConsumer, entry.arg);
                    // inform all consumers about update completed
                    iterCons = entry.consumers.begin();
                    endCons  = entry.consumers.end();
                    for (; iterCons != endCons; iterCons++) {
                        if (*iterCons == pConsumer) continue;
                        typename std::map<ResourceConsumer<T_res>*,void*>::iterator iterArg = updateargs.find(*iterCons);
                        void* updatearg = (iterArg != updateargs.end()) ? iterArg->second : NULL;
                        (*iterCons)->ResourceUpdated(pOldResource, entry.resource, updatearg);
                    }
                    return;
                }
            }
        }

    protected:
        /**
         * Has to be implemented by the descendant to create (allocate) a
         * resource identified by \a Key.
         *
         * @param Key       - identifier of the resource
         * @param pConsumer - identifier of the consumer who borrows the
         *                    resource
         * @param pArg      - pointer the descendant can use to store
         *                    informations he might need for destruction of
         *                    the resource
         * @returns  pointer to new resource
         */
        virtual T_res* Create(T_key Key, ResourceConsumer<T_res>* pConsumer, void*& pArg) = 0;

        /**
         * Has to be implemented by the descendant to destroy (free) a
         * resource pointed by \a pResource.
         *
         * @param pResource - pointer to the resource
         * @param pArg      - pointer the descendant might have used when
         *                    Create() was called to store informations
         *                    about the resource
         */
        virtual void Destroy(T_res* pResource, void* pArg) = 0;

        /**
         * Has to be implemented by the descendant to react when a consumer
         * borrows a resource (no matter if freshly created or an already
         * created one). Of course reacting is optional, but the descendant
         * at least has to provide a method with empty body.
         *
         * @param pResource - pointer to the resource
         * @param pConsumer - identifier of the consumer who borrows the
         *                    resource
         * @param pArg      - pointer the descendant might have used when
         *                    Create() was called to store informations
         *                    about the resource, this information can be
         *                    updated by the descendant here
         */
        virtual void OnBorrow(T_res* pResource, ResourceConsumer<T_res>* pConsumer, void*& pArg) = 0;
};

#endif // __RESOURCE_MANAGER__
1	schoenebeck	53	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5	schoenebeck	56	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	53	* *
7			* This program is free software; you can redistribute it and/or modify *
8			* it under the terms of the GNU General Public License as published by *
9			* the Free Software Foundation; either version 2 of the License, or *
10			* (at your option) any later version. *
11			* *
12			* This program is distributed in the hope that it will be useful, *
13			* but WITHOUT ANY WARRANTY; without even the implied warranty of *
14			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15			* GNU General Public License for more details. *
16			* *
17			* You should have received a copy of the GNU General Public License *
18			* along with this program; if not, write to the Free Software *
19			* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
20			* MA 02111-1307 USA *
21			***************************************************************************/
22
23			#ifndef __RESOURCE_MANAGER__
24			#define __RESOURCE_MANAGER__
25
26			#include <set>
27			#include <map>
28
29			/**
30			* Interface class for consumer classes which use a resource managed
31			* by the ResourceManager class.
32			*/
33			template<class T_res>
34			class ResourceConsumer {
35			public:
36			/**
37			* Will be called by the ResourceManager to inform the
38			* consumer that a resource currently used by him is going
39			* to be updated. The consumer can then react by stopping
40			* usage until resource is updated. The ResourceManager will
41			* not update the resource until this method returns. This
42			* method needs to be implemented by the consumer.
43			*
44			* @param pResource - resource going to be updated
45			* @param pUpdateArg - pointer the consumer might use to store
46			* informations he might need when update
47			* process was completed
48			*/
49			virtual void ResourceToBeUpdated(T_res* pResource, void*& pUpdateArg) = 0;
50
51			/**
52			* Will be called by the ResourceManager to inform the
53			* consumer that resource update was completed. This method
54			* needs to be implemented by the consumer.
55			*
56			* @param pOldResource - (now invalid) pointer to the old
57			* resource
58			* @param pNewResource - (valid) pointer to the updated
59			* resource
60			* @param pUpdateArg - pointer the consumer might have used when
61			* ResourceToBeUpdated() was called
62			*/
63			virtual void ResourceUpdated(T_res* pOldResource, T_res* pNewResource, void* pUpdateArg) = 0;
64			};
65
66			/**
67			* Abstract base class for sharing resources between multiple consumers.
68			* A consumer can borrow a resource from the ResourceManager, if the
69			* resource doesn't exist yet it will be created. Other consumers will
70			* just be given the same pointer to the resource then. When all consumers
71			* gave back their pointer to the resource, the resource will be destroyed.
72			* Descendants of this base class have to implement the (protected)
73			* Create() and Destroy() methods to create and destroy a resource.
74			*/
75			template<class T_key, class T_res>
76			class ResourceManager {
77			private:
78			typedef std::set<ResourceConsumer<T_res>*> ConsumerSet;
79			struct resource_entry_t {
80			T_key key;
81			T_res* resource; ///< pointer to the resource
82			ConsumerSet consumers; ///< list of all consumers who currently use the resource
83			void* arg; ///< optional pointer the descendant might use to store informations about the resource
84			};
85			typedef std::map<T_key, resource_entry_t> ResourceMap;
86			ResourceMap ResourceEntries;
87
88			public:
89	letz	386	virtual ~ResourceManager() {}
90	schoenebeck	53	/**
91			* Borrow a resource identified by \a Key. The ResourceManager will
92			* mark the resource as in usage by the consumer given with
93			* \a pConsumer. If the Resource doesn't exist yet it will be
94			* created.
95			*
96			* @param Key - resource identifier
97			* @param pConsumer - identifier of the consumer who borrows it
98			* @returns pointer to resource
99			*/
100			T_res* Borrow(T_key Key, ResourceConsumer<T_res>* pConsumer) {
101			typename ResourceMap::iterator iterEntry = ResourceEntries.find(Key);
102			if (iterEntry == ResourceEntries.end()) {
103			resource_entry_t entry;
104			entry.key = Key;
105			entry.resource = Create(Key, pConsumer, entry.arg);
106			entry.consumers.insert(pConsumer);
107			OnBorrow(entry.resource, pConsumer, entry.arg);
108			ResourceEntries[Key] = entry;
109			return entry.resource;
110			}
111			resource_entry_t& entry = iterEntry->second;
112			entry.consumers.insert(pConsumer);
113			OnBorrow(entry.resource, pConsumer, entry.arg);
114			return entry.resource;
115			}
116
117			/**
118			* Give back a resource. This tells the ResourceManager that the
119			* consumer given by \a pConsumer doesn't need the resource anymore.
120			* If the resource is not needed by any consumer anymore then the
121			* resource will be destroyed.
122			*
123			* @param pResource - pointer to resource
124			* @param pConsumer - identifier of the consumer who borrowed the
125			* resource
126			*/
127			void HandBack(T_res* pResource, ResourceConsumer<T_res>* pConsumer) {
128			typename ResourceMap::iterator iter = ResourceEntries.begin();
129			typename ResourceMap::iterator end = ResourceEntries.end();
130			for (; iter != end; iter++) {
131	schoenebeck	351	if (iter->second.resource == pResource) {
132	schoenebeck	53	resource_entry_t& entry = iter->second;
133			entry.consumers.erase(pConsumer);
134			if (entry.consumers.empty()) {
135			ResourceEntries.erase(iter);
136			Destroy(entry.resource, entry.arg);
137			}
138			return;
139			}
140			}
141			}
142
143			/**
144			* Request update of a resource.
145			*
146			* @param pResource - resource to be updated
147			* @param pConsumer - consumer who requested the update
148			*/
149			void Update(T_res* pResource, ResourceConsumer<T_res>* pConsumer) {
150			typename ResourceMap::iterator iter = ResourceEntries.begin();
151			typename ResourceMap::iterator end = ResourceEntries.end();
152			for (; iter != end; iter++) {
153	schoenebeck	351	if (iter->second.resource == pResource) {
154	schoenebeck	53	resource_entry_t& entry = iter->second;
155			// inform all consumers about pending update
156			std::map<ResourceConsumer<T_res>,void> updateargs;
157			typename ConsumerSet::iterator iterCons = entry.consumers.begin();
158			typename ConsumerSet::iterator endCons = entry.consumers.end();
159			for (; iterCons != endCons; iterCons++) {
160			if (*iterCons == pConsumer) continue;
161			void* updatearg = NULL;
162			(*iterCons)->ResourceToBeUpdated(entry.resource, updatearg);
163			if (updatearg) updateargs[*iterCons] = updatearg;
164			}
165			// update resource
166			T_res* pOldResource = entry.resource;
167			Destroy(entry.resource, entry.arg);
168			entry.resource = Create(entry.key, pConsumer, entry.arg);
169			// inform all consumers about update completed
170			iterCons = entry.consumers.begin();
171			endCons = entry.consumers.end();
172			for (; iterCons != endCons; iterCons++) {
173			if (*iterCons == pConsumer) continue;
174			typename std::map<ResourceConsumer<T_res>,void>::iterator iterArg = updateargs.find(*iterCons);
175			void* updatearg = (iterArg != updateargs.end()) ? iterArg->second : NULL;
176			(*iterCons)->ResourceUpdated(pOldResource, entry.resource, updatearg);
177			}
178			return;
179			}
180			}
181			}
182
183			protected:
184			/**
185			* Has to be implemented by the descendant to create (allocate) a
186			* resource identified by \a Key.
187			*
188			* @param Key - identifier of the resource
189			* @param pConsumer - identifier of the consumer who borrows the
190			* resource
191			* @param pArg - pointer the descendant can use to store
192			* informations he might need for destruction of
193			* the resource
194			* @returns pointer to new resource
195			*/
196			virtual T_res* Create(T_key Key, ResourceConsumer<T_res>* pConsumer, void*& pArg) = 0;
197
198			/**
199			* Has to be implemented by the descendant to destroy (free) a
200			* resource pointed by \a pResource.
201			*
202			* @param pResource - pointer to the resource
203			* @param pArg - pointer the descendant might have used when
204			* Create() was called to store informations
205			* about the resource
206			*/
207			virtual void Destroy(T_res* pResource, void* pArg) = 0;
208
209			/**
210			* Has to be implemented by the descendant to react when a consumer
211			* borrows a resource (no matter if freshly created or an already
212			* created one). Of course reacting is optional, but the descendant
213			* at least has to provide a method with empty body.
214			*
215			* @param pResource - pointer to the resource
216			* @param pConsumer - identifier of the consumer who borrows the
217			* resource
218			* @param pArg - pointer the descendant might have used when
219			* Create() was called to store informations
220			* about the resource, this information can be
221			* updated by the descendant here
222			*/
223			virtual void OnBorrow(T_res* pResource, ResourceConsumer<T_res>* pConsumer, void*& pArg) = 0;
224			};
225
226			#endif // __RESOURCE_MANAGER__