From 74b5cf6a049ca258db97a0320f63ac4ee2cc7611 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=ADn=20Lucas=20Golini?= Date: Wed, 16 Jan 2013 23:25:26 -0300 Subject: [PATCH] Documented EE::System. --- include/eepp/ee.hpp | 6 +- include/eepp/system/cobjectloader.hpp | 6 +- include/eepp/system/cresourceloader.hpp | 20 +++++++ include/eepp/system/cthread.hpp | 75 +++++++++++++++++++++++- include/eepp/system/safedatapointer.hpp | 4 ++ include/eepp/system/tcontainer.hpp | 5 +- include/eepp/system/tresourcemanager.hpp | 47 ++++++++++++--- projects/linux/ee.creator.user | 2 +- 8 files changed, 144 insertions(+), 21 deletions(-) diff --git a/include/eepp/ee.hpp b/include/eepp/ee.hpp index 9c593e59c..bafd9085d 100755 --- a/include/eepp/ee.hpp +++ b/include/eepp/ee.hpp @@ -29,9 +29,9 @@ STATE: It's looking good. @TODO Improve documentation. - STATE: EE ( Base ) commented what is needed. - EE::Window commented. - EE::System 80 % commented, easy to understand. + STATE: EE ( Base ) documented what is needed. + EE::Window documented. + EE::System documented. EE::Graphics 50 % commented. EE::Audio 50 % commented. EE::Math 30 to 40 % commented. diff --git a/include/eepp/system/cobjectloader.hpp b/include/eepp/system/cobjectloader.hpp index d6db02b82..5af81c63f 100644 --- a/include/eepp/system/cobjectloader.hpp +++ b/include/eepp/system/cobjectloader.hpp @@ -30,8 +30,7 @@ class EE_API cObjectLoader : protected cThread { void Load(); /** @brief Starts loading the resource. - ** @param Cb A callback that is called when the resources is loaded. - */ + ** @param Cb A callback that is called when the resource finished loading. */ void Load( ObjLoadCallback Cb ); /** @brief Force to unload the resource from memory in case that it was already loaded. */ @@ -56,8 +55,7 @@ class EE_API cObjectLoader : protected cThread { bool Threaded() const; /** @brief Sets if the loader is asynchronous. - ** This must be called before the load starts. - */ + ** This must be called before the load starts. */ void Threaded( const bool& threaded ); /** @return The object loader type */ diff --git a/include/eepp/system/cresourceloader.hpp b/include/eepp/system/cresourceloader.hpp index f33f83100..a481cdcd6 100644 --- a/include/eepp/system/cresourceloader.hpp +++ b/include/eepp/system/cresourceloader.hpp @@ -8,6 +8,7 @@ namespace EE { namespace System { #define THREADS_AUTO (0xFFFFFFFF) +/** @brief A simple resource loader that can load a batch of resources synchronously or asynchronously */ class EE_API cResourceLoader { public: typedef cb::Callback1 ResLoadCallback; @@ -17,29 +18,47 @@ class EE_API cResourceLoader { virtual ~cResourceLoader(); + /** @brief Adds a resource to load. + ** Must be called before the loading starts. + ** Once an object loader is added to the resource loader, the instance of that object will be managed and released by the loader. + ** @param Object The instance object loader to load + */ void Add( cObjectLoader * Object ); + /** @brief Starts loading the resources. + ** @param Cb A callback that is called when the resources finished loading. */ void Load( ResLoadCallback Cb ); + /** @brief Starts loading the resources. */ void Load(); + /** @brief Unload all the resources already loaded. */ void Unload(); + /** @brief Update must be called from the thread that started the loading to update the state of the resource loader. */ virtual void Update(); + /** @returns If the resources were loaded. */ virtual bool IsLoaded(); + /** @returns If the resources are still loading. */ virtual bool IsLoading(); + /** @returns If the resource loader is asynchronous */ bool Threaded() const; + /** @brief Sets if the resource loader is asynchronous. + ** This must be called before the load starts. */ void Threaded( const bool& threaded ); + /** @brief Clears the resources added to load that werent loaded, and delete the instances of the loaders. + ** @param ClearObjectsLoaded Sets if the objects loader that were already loaded must be also deleted ( it will not unload the loaded resources, but the instance of the object loader ). */ bool Clear( const bool& ClearObjectsLoaded = true ); /** @return The aproximate percent of progress ( between 0 and 100 ) */ eeFloat Progress(); + /** @returns The number of resources added to load. */ Uint32 Count() const; protected: bool mLoaded; @@ -52,6 +71,7 @@ class EE_API cResourceLoader { std::list mObjsLoaded; void SetThreads(); + virtual void SetLoaded(); }; diff --git a/include/eepp/system/cthread.hpp b/include/eepp/system/cthread.hpp index 4a7a02d77..79b7274ae 100755 --- a/include/eepp/system/cthread.hpp +++ b/include/eepp/system/cthread.hpp @@ -13,24 +13,93 @@ class EE_API cThread { public: typedef void (*FuncType)(void*); + /** @brief Construct the thread from a functor with no argument + ** This constructor works for function objects, as well + ** as free function. + ** Use this constructor for this kind of function: + @code + void function(); + + --- or ---- + + struct Functor + { + void operator()(); + }; + @endcode + Note: this does *not* run the thread, use Launch(). + @param function Functor or free function to use as the entry point of the thread + */ template cThread( F function ); + /** @brief Construct the thread from a functor with an argument + ** This constructor works for function objects, as well + ** as free function. + ** It is a template, which means that the argument can + ** have any type (int, std::string, void*, Toto, ...). + ** Use this constructor for this kind of function: + ** @code + void function(int arg); + + --- or ---- + + struct Functor + { + void operator()(std::string arg); + }; + @endcode + Note: this does *not* run the thread, use Launch(). + ** @param function Functor or free function to use as the entry point of the thread + ** @param argument argument to forward to the function */ template cThread( F function, A argument ); + /** @brief Construct the thread from a member function and an object + ** This constructor is template, which means that you can + ** use it with any class. + ** Use this constructor for this kind of function: + ** @code + class MyClass + { + public : + void function(); + }; + ** @endcode + ** Note: this does *not* run the thread, use Launch(). + ** @param function Entry point of the thread + ** @param object Pointer to the object to use **/ template cThread( void(C::*function)(), C* object ); + /** @brief Destructor + ** This destructor calls Wait(), so that the internal thread + ** cannot survive after its sf::Thread instance is destroyed. */ virtual ~cThread(); - /** Launch the thread */ + /** @brief Run the thread + ** This function starts the entry point passed to the + ** thread's constructor, and returns immediately. + ** After this function returns, the thread's function is + ** running in parallel to the calling code. */ virtual void Launch(); - /** Wait the thread until end */ + /** @brief Wait until the thread finishes. + ** This function will block the execution until the + ** thread's function ends. + ** Warning: if the thread function never ends, the calling + ** thread will block forever. + ** If this function is called from its owner thread, it + ** returns without doing anything. */ void Wait(); - /** Terminate the thread */ + /** @brief Terminate the thread + ** This function immediately stops the thread, without waiting + ** for its function to finish. + ** Terminating a thread with this function is not safe, + ** and can lead to local variables not being destroyed + ** on some operating systems. You should rather try to make + ** the thread function terminate by itself. */ void Terminate(); protected: cThread(); diff --git a/include/eepp/system/safedatapointer.hpp b/include/eepp/system/safedatapointer.hpp index 4a6000f4c..f7b77af07 100644 --- a/include/eepp/system/safedatapointer.hpp +++ b/include/eepp/system/safedatapointer.hpp @@ -12,9 +12,13 @@ class EE_API SafeDataPointer { SafeDataPointer( Uint8 * data, Uint32 size ); + /** @brief The destructor deletes the buffer */ ~SafeDataPointer(); + /** Pointer to the buffer */ Uint8 * Data; + + /** Buffer size */ Uint32 DataSize; }; diff --git a/include/eepp/system/tcontainer.hpp b/include/eepp/system/tcontainer.hpp index 9f89a0dad..166eed0d4 100644 --- a/include/eepp/system/tcontainer.hpp +++ b/include/eepp/system/tcontainer.hpp @@ -6,7 +6,7 @@ namespace EE { namespace System { -/** @brief A simple resource container template */ +/** @brief A simple resource container template, to keep track of the resources loaded. */ template class tContainer { public: @@ -14,10 +14,13 @@ class tContainer { virtual ~tContainer(); + /** @brief Add to the list the resource. */ T * Add( T * Resource ); + /** @brief Remove from the list the resource. */ bool Remove( T * Resource ); + /** @returns The number of resources added to the container. */ Uint32 Count(); protected: std::list mResources; diff --git a/include/eepp/system/tresourcemanager.hpp b/include/eepp/system/tresourcemanager.hpp index 1813c33a9..626745465 100644 --- a/include/eepp/system/tresourcemanager.hpp +++ b/include/eepp/system/tresourcemanager.hpp @@ -7,44 +7,64 @@ namespace EE { namespace System { /** @brief A simple resource manager. It keeps a list of the resources, and free the instances of the resources when the manager is closed. -* Resources must have Id() and Name() properties. Id() is the string hash of Name(). -*/ +** Resources must have Id() and Name() properties. Id() is the string hash of Name(). */ template class tResourceManager { public: /** @param UniqueId Indicates if the resources id must be unique */ tResourceManager( bool UniqueId = true ); + /** @brief The destructor will call Destroy() and destroy all the resources added to the manager */ virtual ~tResourceManager(); + /** @brief Add the resource to the resource manager + ** @param Resource The resource to be managed by the manager */ virtual T * Add( T * Resource ); + /** @brief Removes the resource from the manager + ** @param Resource The resource to remove + ** @param Delete Indicates if the resource must be destroyed after being removed from the manager */ bool Remove( T * Resource, bool Delete = true ); + /** @brief Removes the resource by its id + ** @see Remove */ bool RemoveById( const Uint32& Id, bool Delete = true ); + /** @brief Removes the resource by its name + ** @see Remove */ bool RemoveByName( const std::string& Name, bool Delete = true ); + /** @returns A resource by its name. If not found returns NULL. */ T * GetByName( const std::string& Name ); + /** @returns A resource by its id. If not found returns NULL. */ T * GetById( const Uint32& Id ); + /** @returns The number of resources added */ Uint32 Count(); + /** @returns The number of resources that where added with the indicated name. */ Uint32 Count( const std::string& Name ); + /** @returns The number of resources that where added with the indicated id. */ Uint32 Count( const Uint32& Id ); - Uint32 Exists( const std::string& Name ); + /** @returns If the resource name exists in the resources list. */ + bool Exists( const std::string& Name ); - Uint32 ExistsId( const Uint32& Id ); + /** @returns If the resource id exists in the resources list. */ + bool ExistsId( const Uint32& Id ); + /** @brief Destroy all the resources added ( delete the instances of the resources ) */ void Destroy(); + /** @brief Prints all the resources names added to the manager. */ void PrintNames(); + /** @returns A reference to the resources list of the manager. */ std::list& GetResources(); + /** @brief Indicates if the resource manager is destroy the resources. */ const bool& IsDestroying() const; protected: std::list mResources; @@ -75,8 +95,11 @@ void tResourceManager::Destroy() { mIsDestroying = true; - for ( it = mResources.begin() ; it != mResources.end(); it++ ) + for ( it = mResources.begin() ; it != mResources.end(); it++ ) { eeSAFE_DELETE( (*it) ); + } + + mResources.clear(); mIsDestroying = false; } @@ -141,13 +164,19 @@ bool tResourceManager::RemoveByName( const std::string& Name, bool Delete ) { } template -Uint32 tResourceManager::Exists( const std::string& Name ) { - return Count( Name ); +bool tResourceManager::Exists( const std::string& Name ) { + return ExistsId( String::Hash( Name ) ); } template -Uint32 tResourceManager::ExistsId( const Uint32& Id ) { - return Count( Id ); +bool tResourceManager::ExistsId( const Uint32& Id ) { + typename std::list::iterator it; + + for ( it = mResources.begin() ; it != mResources.end(); it++ ) + if ( (*it)->Id() == Id ) + return true; + + return false; } template diff --git a/projects/linux/ee.creator.user b/projects/linux/ee.creator.user index 9f4893b49..2cbcacb1b 100644 --- a/projects/linux/ee.creator.user +++ b/projects/linux/ee.creator.user @@ -1,6 +1,6 @@ - + ProjectExplorer.Project.ActiveTarget