source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreResourceBackgroundQueue.h @ 1809

Revision 1809, 10.2 KB checked in by gumbau, 18 years ago (diff)
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef __ResourceBackgroundQueue_H__
26#define __ResourceBackgroundQueue_H__
27
28
29#include "OgrePrerequisites.h"
30#include "OgreCommon.h"
31#include "OgreSingleton.h"
32
33#if OGRE_THREAD_SUPPORT
34#       include <boost/thread/thread.hpp>
35#       include <boost/thread/condition.hpp>
36#endif
37
38namespace Ogre {
39
40        /// Identifier of a background process
41        typedef unsigned long BackgroundProcessTicket;
42
43        /** This abstract listener interface lets you get immediate notifications of
44                completed background processes instead of having to check ticket
45                statuses.
46        @note
47                These callbacks occur in the <i>background thread</i>, not the thread
48                which you queued your request from. You should only use this method
49                if you understand the implications of threading and the use of locks,
50                monitor objects or other such thread safety techniques. If you don't,
51                use the simpler 'ticket' approach and poll the isProcessComplete()
52                method
53                to determine when your processes complete.
54        */
55        class _OgreExport ResourceBackgroundQueueListener
56        {
57        public:
58                /** Called when a requested operation completes.
59                @note Called in the <i>background thread</i>, not your queueing
60                thread, so be careful!
61                */
62                virtual void operationCompleted(BackgroundProcessTicket ticket) = 0;
63        };
64       
65        /** This class is used to perform Resource operations in a
66                background thread.
67        @remarks
68                If threading is enabled, Ogre will create a single background thread
69                which can be used to load / unload resources in parallel. Only one
70                resource will be processed at once in this background thread, but it
71                will be in parallel with the main thread.
72        @par
73                The general approach here is that on requesting a background resource
74                process, your request is placed on a queue ready for the background
75                thread to be picked up, and you will get a 'ticket' back, identifying
76                the request. Your call will then return and your thread can
77                proceed, knowing that at some point in the background the operation wil
78                be performed. In it's own thread, the resource operation will be
79                performed, and once finished the ticket will be marked as complete.
80                You can check the status of tickets by calling isProcessComplete()
81                from your queueing thread. It is also possible to get immediate
82                callbacks on completion, but these callbacks happen in the background
83                loading thread (not your calling thread), so should only be used if you
84                really understand multithreading.
85        @note
86                This class will only perform tasks in a background thread if
87                OGRE_THREAD_SUPPORT is defined to be 1. Otherwise, all methods will
88                call their exact equivalents in ResourceGroupManager synchronously.
89        */
90        class _OgreExport ResourceBackgroundQueue : public Singleton<ResourceBackgroundQueue>
91        {
92        protected:
93                /** Enumerates the type of requests */
94                enum RequestType
95                {
96                        RT_INITIALISE_GROUP,
97                        RT_INITIALISE_ALL_GROUPS,
98                        RT_LOAD_GROUP,
99                        RT_LOAD_RESOURCE,
100                        RT_SHUTDOWN
101                };
102                /** Encapsulates a queued request for the background queue */
103                struct Request
104                {
105                        BackgroundProcessTicket ticketID;
106                        RequestType type;
107                        String resourceName;
108                        String resourceType;
109                        String groupName;
110                        bool isManual;
111                        ManualResourceLoader* loader;
112                        const NameValuePairList* loadParams;
113                        ResourceBackgroundQueueListener* listener;
114                };
115                typedef std::list<Request> RequestQueue;
116                typedef std::map<BackgroundProcessTicket, Request*> RequestTicketMap;
117               
118                /// Queue of requests, used to store and order requests
119                RequestQueue mRequestQueue;
120               
121                /// Request lookup by ticket
122                RequestTicketMap mRequestTicketMap;
123
124                /// Next ticket ID
125                unsigned long mNextTicketID;
126
127#if OGRE_THREAD_SUPPORT
128                /// The single background thread which will process loading requests
129                boost::thread* mThread;
130                /// Synchroniser token to wait / notify on queue
131                boost::condition mCondition;
132                /// Thread function
133                static void threadFunc(void);
134                /// Internal method for adding a request; also assigns a ticketID
135                BackgroundProcessTicket addRequest(Request& req);
136#else
137                /// Dummy
138                void* mThread;
139#endif
140
141                /// Private mutex, not allowed to lock from outside
142                OGRE_AUTO_MUTEX
143
144        public:
145                ResourceBackgroundQueue();
146                virtual ~ResourceBackgroundQueue();
147
148                /** Initialise the background queue system. */
149                virtual void initialise(void);
150               
151                /** Shut down the background queue system. */
152                virtual void shutdown(void);
153
154                /** Initialise a resource group in the background.
155                @see ResourceGroupManager::initialiseResourceGroup
156                @param name The name of the resource group to initialise
157                @param listener Optional callback interface, take note of warnings in
158                        the header and only use if you understand them.
159                @returns Ticket identifying the request, use isProcessComplete() to
160                        determine if completed if not using listener
161                */
162                virtual BackgroundProcessTicket initialiseResourceGroup(
163                        const String& name, ResourceBackgroundQueueListener* listener = 0);
164
165                /** Initialise all resource groups which are yet to be initialised in
166                        the background.
167                @see ResourceGroupManager::intialiseResourceGroup
168                @param listener Optional callback interface, take note of warnings in
169                        the header and only use if you understand them.
170                @returns Ticket identifying the request, use isProcessComplete() to
171                        determine if completed if not using listener
172                */
173                virtual BackgroundProcessTicket initialiseAllResourceGroups(
174                        ResourceBackgroundQueueListener* listener = 0);
175                /** Loads a resource group in the background.
176                @see ResourceGroupManager::intialiseResourceGroup
177                @param listener Optional callback interface, take note of warnings in
178                        the header and only use if you understand them.
179                @returns Ticket identifying the request, use isProcessComplete() to
180                        determine if completed if not using listener
181                */
182                virtual BackgroundProcessTicket loadResourceGroup(const String& name,
183                        ResourceBackgroundQueueListener* listener = 0);
184
185
186                /** Load a single resource in the background.
187                @see ResourceManager::load
188                @param resType The type of the resource
189                        (from ResourceManager::getResourceType())
190                @param name The name of the Resource
191                @param group The resource group to which this resource will belong
192                @param isManual Is the resource to be manually loaded? If so, you should
193                        provide a value for the loader parameter
194                @param loader The manual loader which is to perform the required actions
195                        when this resource is loaded; only applicable when you specify true
196                        for the previous parameter. NOTE: must be thread safe!!
197        @param loadParams Optional pointer to a list of name/value pairs
198            containing loading parameters for this type of resource. Remember
199                        that this must have a lifespan longer than the return of this call!
200                */
201                virtual BackgroundProcessTicket load(
202                        const String& resType, const String& name,
203            const String& group, bool isManual = false,
204                        ManualResourceLoader* loader = 0,
205                        const NameValuePairList* loadParams = 0,
206                        ResourceBackgroundQueueListener* listener = 0);
207
208                /** Returns whether a previously queued process has completed or not.
209                @param ticket The ticket which was returned when the process was queued
210                @returns true if process has completed (or if the ticket is
211                        unrecognised), false otherwise
212                @note Tickets are not stored onced complete so do not accumulate over
213                        time.
214                This is why a non-existent ticket will return 'true'.
215                */
216                virtual bool isProcessComplete(BackgroundProcessTicket ticket);
217
218                /** Override standard Singleton retrieval.
219        @remarks
220        Why do we do this? Well, it's because the Singleton
221        implementation is in a .h file, which means it gets compiled
222        into anybody who includes it. This is needed for the
223        Singleton template to work, but we actually only want it
224        compiled into the implementation of the class based on the
225        Singleton, not all of them. If we don't change this, we get
226        link errors when trying to use the Singleton-based class from
227        an outside dll.
228        @par
229        This method just delegates to the template version anyway,
230        but the implementation stays in this single compilation unit,
231        preventing link errors.
232        */
233        static ResourceBackgroundQueue& getSingleton(void);
234        /** Override standard Singleton retrieval.
235        @remarks
236        Why do we do this? Well, it's because the Singleton
237        implementation is in a .h file, which means it gets compiled
238        into anybody who includes it. This is needed for the
239        Singleton template to work, but we actually only want it
240        compiled into the implementation of the class based on the
241        Singleton, not all of them. If we don't change this, we get
242        link errors when trying to use the Singleton-based class from
243        an outside dll.
244        @par
245        This method just delegates to the template version anyway,
246        but the implementation stays in this single compilation unit,
247        preventing link errors.
248        */
249        static ResourceBackgroundQueue* getSingletonPtr(void);
250               
251
252        };
253
254
255}
256
257#endif
258
Note: See TracBrowser for help on using the repository browser.