From 35247d6862d9f26b862b5de463a83c1ce29e7a72 Mon Sep 17 00:00:00 2001 From: Sunwook Bae Date: Thu, 24 Oct 2013 15:57:26 +0900 Subject: [PATCH] Update Runtime document from LB Change-Id: Ib145695ebc9a6ea2eedba55987c5c1f5bafdee3b Signed-off-by: Sunwook Bae --- inc/FBaseRt.h | 4 +- inc/FBaseRtEvent.h | 35 ++++++------ inc/FBaseRtEventDrivenThread.h | 32 +++++------ inc/FBaseRtIEventArg.h | 6 +- inc/FBaseRtIEventListener.h | 6 +- inc/FBaseRtIRunnable.h | 12 ++-- inc/FBaseRtITimerEventListener.h | 4 +- inc/FBaseRtIWaitingLoopCondition.h | 8 ++- inc/FBaseRtLibrary.h | 12 ++-- inc/FBaseRtMemoryManager.h | 16 +++--- inc/FBaseRtMonitor.h | 26 ++++----- inc/FBaseRtMonitorGuard.h | 12 ++-- inc/FBaseRtMutex.h | 42 +++++++------- inc/FBaseRtMutexGuard.h | 28 ++++----- inc/FBaseRtSemaphore.h | 27 ++++----- inc/FBaseRtSemaphoreGuard.h | 114 ++++++++++++++++++------------------- inc/FBaseRtThread.h | 63 ++++++++++---------- inc/FBaseRtTimer.h | 67 +++++++++++----------- inc/FBaseRtTypes.h | 8 +-- inc/FBaseRtWaitingLoop.h | 52 +++++++++-------- 20 files changed, 293 insertions(+), 281 deletions(-) diff --git a/inc/FBaseRt.h b/inc/FBaseRt.h index e700caa..bec9a9f 100644 --- a/inc/FBaseRt.h +++ b/inc/FBaseRt.h @@ -48,14 +48,14 @@ * @since 2.0 * * @remarks @b Header @b %file: @b \#include @b @n - * @b Library : @b osp-appfw + * @b Library: @b osp-appfw * * * The %Runtime namespace contains classes for running applications. * The runtime environment includes threading, synchronization objects, * and timer. * - * For more information on the %Base::Runtime namespace features, see Runtime. + * For more information on the %Runtime namespace features, see Runtime. * * The following diagram illustrates the relationships between the classes belonging to the %Runtime namespace. * @image html base_runtime_namespace_classdiagram.png diff --git a/inc/FBaseRtEvent.h b/inc/FBaseRtEvent.h index 2f4501b..34155b7 100644 --- a/inc/FBaseRtEvent.h +++ b/inc/FBaseRtEvent.h @@ -18,7 +18,7 @@ * @file FBaseRtEvent.h * @brief This is the header file for the %Event class. * - * This file contains the declarations of the %Event class. + * This header file contains the declarations of the %Event class. */ #ifndef _FBASE_RT_EVENT_H_ @@ -33,12 +33,12 @@ class IEventArg; class IEventListener; /** * @class Event -* @brief This class provides methods for notifying events with argument to its listeners. +* @brief This class provides methods for notifying events with arguments to its listeners. * @since 2.0 * -* The %Event class provides methods for notifying events with argument to its listeners. -* Because bounded to either default thread or event-driven thread, it cannot be created on worker thread. -* It supports two types of listeners; one is called on the thread where the event is fired, and another is called on the thread where the listener was registered. +* The %Event class provides methods for notifying events with arguments to its listeners. +* Because it is bounded to either a default thread or an event-driven thread, it cannot be created on a worker thread. +* It supports two types of listeners; one is called on the thread where the event is fired, and another is called on the thread where the listener is registered. * * @code * @@ -120,12 +120,12 @@ public: * @since 2.0 * * @return An error code - * @param[in] listener Listener to add - * @param[in] calledByCallerThread true, to call the listener on the caller thread of this method - * false, to call the listener on the thread in which the event is fired. - * @exception E_SUCCESS This method is successful. + * @param[in] listener The listener to add + * @param[in] calledByCallerThread Set to @c true, to call the listener on the caller thread of this method, @n + * else @c false, to call the listener on the thread in which the event is fired. + * @exception E_SUCCESS The method is successful. * @exception E_OBJ_ALREADY_EXIST The listener already exists. - * @exception E_INVALID_OPERATION calledByCallerThread is set to true but the caller thread is a worker thread. + * @exception E_INVALID_OPERATION The specified @c calledByCallerThread is @c true but the caller thread is a worker thread. */ result AddListener(IEventListener& listener, bool calledByCallerThread = true); @@ -136,9 +136,9 @@ public: * @since 2.0 * * @return An error code - * @param[in] listener Listener to remove - * @exception E_SUCCESS This method is successful. - * @exception E_OBJ_NOT_FOUND The listener is not found. + * @param[in] listener The listener to remove + * @exception E_SUCCESS The method is successful. + * @exception E_OBJ_NOT_FOUND The listener has not been found. */ result RemoveListener(IEventListener& listener); @@ -148,11 +148,12 @@ public: * @since 2.0 * * @return An error code - * @param[in] arg The event argument. - * @exception E_SUCCESS This method is successful. - * @exception E_INVALID_STATE This event has not been initialized. + * @param[in] arg The event argument + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_STATE This event has not been initialized. * - * @remarks This takes the ownership of @c arg. So arg should be created on a heap and should not be deleted by caller. + * @remarks This takes the ownership of @c arg. @n + * So @c arg should be created on a heap and should not be deleted by caller. */ result Fire(IEventArg& arg); diff --git a/inc/FBaseRtEventDrivenThread.h b/inc/FBaseRtEventDrivenThread.h index 0f04666..a26f9e5 100644 --- a/inc/FBaseRtEventDrivenThread.h +++ b/inc/FBaseRtEventDrivenThread.h @@ -35,7 +35,7 @@ namespace Tizen { namespace Base { namespace Runtime /** * @class EventDrivenThread - * @brief This class is the fundamental class for the asynchronous execution of a thread. + * @brief This class is the fundamental class for the asynchronous execution of a thread. * * @since 2.0 * @@ -151,7 +151,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID); @@ -162,11 +162,11 @@ public: * @since 2.0 * * @return An error code - * @param[in] name The name of the thread + * @param[in] name The name of the thread * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(const Tizen::Base::String& name, long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID); @@ -206,13 +206,13 @@ public: /** * Called before the message loop is started. @n - * If this method returns @c false, the thread is terminated immediately. + * If the %OnStart() method returns @c false, the thread is terminated immediately. * * @since 2.0 * - * @return @c true if this thread can be run, @n - * else @c false - * @remarks You can initialize the event or event listener in this method for running this thread. + * @return @c true if this thread runs, @n + * else @c false + * @remarks The event or event listener in this method can be initialized for running this thread. * */ virtual bool OnStart(void); @@ -222,7 +222,7 @@ public: * * @since 2.0 * - * @remarks You can finalize the event or event listener in this method for running this thread. + * @remarks The event or event listener in this method can be finalized for running this thread. * */ virtual void OnStop(void); @@ -236,12 +236,12 @@ public: * If overridden, it may not work as expected. * * @return An error code - * @param[in] requestId The user-defined event ID - * @param[in] pArgs A pointer to a list of arguments - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_STATE The thread is in an invalid state. - * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_SYSTEM A system error has occurred. + * @param[in] requestId The user-defined event ID + * @param[in] pArgs A pointer to the list of arguments + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_STATE The thread is in an invalid state. + * @exception E_OUT_OF_MEMORY The memory is insufficient. + * @exception E_SYSTEM A system error has occurred. * * @see OnUserEventReceivedN() */ @@ -253,7 +253,7 @@ public: * @since 2.0 * * @param[in] requestId The user-defined event ID - * @param[in] pArgs A pointer to a list of arguments + * @param[in] pArgs A pointer to the list of arguments * * @see SendUserEvent() */ diff --git a/inc/FBaseRtIEventArg.h b/inc/FBaseRtIEventArg.h index 3137e42..342b56c 100644 --- a/inc/FBaseRtIEventArg.h +++ b/inc/FBaseRtIEventArg.h @@ -28,11 +28,11 @@ namespace Tizen { namespace Base { namespace Runtime { /** * @interface IEventArg -* @brief This interface is a tagging interface that all event argument must implement. +* @brief This interface is a tagging interface that all event arguments must implement. * -* @since 2.0 +* @since 2.0 * -* The %IEventArg interface is a tagging interface that all event argument must implement. +* The %IEventArg interface is a tagging interface that all event arguments must implement. */ class IEventArg { diff --git a/inc/FBaseRtIEventListener.h b/inc/FBaseRtIEventListener.h index b0e248b..f734d26 100644 --- a/inc/FBaseRtIEventListener.h +++ b/inc/FBaseRtIEventListener.h @@ -15,8 +15,8 @@ // /** - * @file FBaseRtIEventListener.h - * @brief This is the header file for the %IEventListener interface. + * @file FBaseRtIEventListener.h + * @brief This is the header file for the %IEventListener interface. * * This header contains the declarations of the %IEventListener interface. */ @@ -37,7 +37,7 @@ namespace Tizen { namespace Base { namespace Runtime * @since 2.0 * * The %IEventListener interface is a tagging interface that all event listeners must implement. - * The event listener can listen when the specific event occurs. The event listener + * The event listener can listen when a specific event occurs. The event listener * has several methods, and each method is called when a specific event occurs. * */ diff --git a/inc/FBaseRtIRunnable.h b/inc/FBaseRtIRunnable.h index ee587e9..fdc964e 100644 --- a/inc/FBaseRtIRunnable.h +++ b/inc/FBaseRtIRunnable.h @@ -31,16 +31,16 @@ namespace Tizen { namespace Base { namespace Runtime { /** * @interface IRunnable - * @brief This interface is the basic unit of the task. Also, it is the execution unit of - * the thread. This interface must be inherited by the class whose instances will + * @brief This interface is the basic unit of a task. Also, it is the execution unit of + * the thread. This interface must be inherited by the class whose instances are * run on the thread. * * @since 2.0 * * @remarks Classes which inherit the %IRunnable interface must implement the Run() method. * - * The %IRunnable interface is the basic unit of the task. Also, it is the execution unit of - * the thread. This interface must be inherited by the class whose instances will + * The %IRunnable interface is the basic unit of a task. Also, it is the execution unit of + * the thread. This interface must be inherited by the class whose instances are * run on the thread. * @n * For more information on the class features, see Thread Programming. @@ -89,14 +89,14 @@ public: /** * Runs the task. @n - * This method is an executable body of the task. In many cases, this method is called by the thread. + * The %Run() method is an executable body of the task. In many cases, this method is called by the thread. * Although this method can return the result of the execution, the returned value might be discarded * by the executor of this task. * * @since 2.0 * * @return A pointer to the result of the task, @n - * else @c null + * else @c null if it fails */ virtual Tizen::Base::Object* Run(void) = 0; }; // IRunnable diff --git a/inc/FBaseRtITimerEventListener.h b/inc/FBaseRtITimerEventListener.h index f5e9e26..ba026e9 100644 --- a/inc/FBaseRtITimerEventListener.h +++ b/inc/FBaseRtITimerEventListener.h @@ -42,7 +42,7 @@ class Timer; * * For more information on the class features, see Timer. * - * @see Timer() + * @see Timer */ class _OSP_EXPORT_ ITimerEventListener : virtual public IEventListener @@ -60,7 +60,7 @@ public: * * @since 2.0 * - * @param[in] timer The timer that has expired + * @param[in] timer The expired timer */ virtual void OnTimerExpired(Timer& timer) = 0; diff --git a/inc/FBaseRtIWaitingLoopCondition.h b/inc/FBaseRtIWaitingLoopCondition.h index 8e166ff..ba97476 100755 --- a/inc/FBaseRtIWaitingLoopCondition.h +++ b/inc/FBaseRtIWaitingLoopCondition.h @@ -18,6 +18,7 @@ * @file FBaseRtIWaitingLoopCondition.h * @brief This is the header file for the %IWaitingLoopCondition interface. * + * This header file contains the declarations of the %IWaitingLoopCondition interface. */ #ifndef _FBASE_RT_WAITING_LOOP_CONDITION_H_ #define _FBASE_RT_WAITING_LOOP_CONDITION_H_ @@ -27,7 +28,7 @@ namespace Tizen { namespace Base { namespace Runtime { /* * @interface IWaitingLoopCondition - * @brief This interface provides the method to check whether the WaitingLoopCondition is met. + * @brief This interface provides a method to check whether the WaitingLoopCondition is met. * * @since 2.0 */ @@ -35,14 +36,15 @@ class _OSP_EXPORT_ IWaitingLoopCondition { public: /* - * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called. + * This polymorphic destructor should be overridden if required. @n + * This way, the destructors of the derived classes are called when the destructor of this interface is called. * * @since 2.0 */ virtual ~IWaitingLoopCondition(void) {} /* - * Check whether the waiting loop condition is met + * Checks whether the waiting loop condition is met. * * @since 2.0 * diff --git a/inc/FBaseRtLibrary.h b/inc/FBaseRtLibrary.h index c1f1edc..77265bf 100644 --- a/inc/FBaseRtLibrary.h +++ b/inc/FBaseRtLibrary.h @@ -31,14 +31,14 @@ namespace Tizen { namespace Base { namespace Runtime { /** * @class Library - * @brief This is the class for shared library. + * @brief This is the class for the shared library. * * @since 2.0 * * @final This class is not intended for extension. * * The %Library class loads the shared library with the given file path. - * It loads the library in current process' memory space, and application can use this library explicitly. + * It loads the library in current process' memory space, and the application can use this library explicitly. */ class _OSP_EXPORT_ Library : public Tizen::Base::Object @@ -64,8 +64,8 @@ public: * * @since 2.0 * - * @return An error code - * @param[in] libraryPath The path of the library file + * @return An error code + * @param[in] libraryPath The path of the library file * @exception E_SUCCESS The method is successful. * @exception E_LIBRARY_NOT_FOUND The library cannot be found. * @exception E_INVALID_ARG The specified @c libraryPath is an empty string. @@ -80,8 +80,8 @@ public: * * @since 2.0 * - * @return The address of the specified symbol - * @param[in] symbol The symbol name + * @return The address of the specified symbol + * @param[in] symbol The symbol name * @exception E_SUCCESS The method is successful. * @exception E_SYMBOL_NOT_FOUND The symbol cannot be found. * @exception E_INVALID_ARG The specified @c symbol is an empty string. diff --git a/inc/FBaseRtMemoryManager.h b/inc/FBaseRtMemoryManager.h index 82e0da5..4a93d05 100644 --- a/inc/FBaseRtMemoryManager.h +++ b/inc/FBaseRtMemoryManager.h @@ -39,13 +39,13 @@ namespace Tizen { namespace Base { namespace Runtime { enum MemoryProtectionMode { MEMORY_PROTECTION_MODE_NONE = 0x0, /**< The memory cannot be accessed */ - MEMORY_PROTECTION_MODE_READ = 0x1, /**< The memory can be read */ - MEMORY_PROTECTION_MODE_WRITE = 0x2, /**< The memory can be modified */ - MEMORY_PROTECTION_MODE_EXEC = 0x4, /**< The memory can be executed */ + MEMORY_PROTECTION_MODE_READ = 0x1, /**< The memory can be read */ + MEMORY_PROTECTION_MODE_WRITE = 0x2, /**< The memory can be modified */ + MEMORY_PROTECTION_MODE_EXEC = 0x4, /**< The memory can be executed */ }; /** - * @class MemoryManager + * @class MemoryManager * @brief This class represents a memory manager for runtime. * * @since 2.0 @@ -86,19 +86,21 @@ class _OSP_EXPORT_ MemoryManager { public: /** - * Changes protection on a memory region. + * Changes the protection on a memory region. * * @since 2.0 * * @return An error code - * @param[in] pAddress The start address of the memory region aligned on a page boundary. + * @param[in] pAddress The start address of the memory region aligned on a page boundary * @param[in] length The length of the memory region in bytes * @param[in] protection The memory protection @n * It is either Tizen::Base::Runtime::MEMORY_PROTECTION_MODE_NONE or a bitwise OR of the * other values in Tizen::Base::Runtime::MemoryProtectionMode. * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred due to an invalid address. - * @exception E_INVALID_ARG The memory address is not valid, or the length is not a multiple of system page size. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The memory address is invalid. + * - The specified @c length is not a multiple of the system page size. */ static result ProtectMemory(const void* pAddress, long long length, unsigned long protection); diff --git a/inc/FBaseRtMonitor.h b/inc/FBaseRtMonitor.h index b9696ac..1fc48fd 100755 --- a/inc/FBaseRtMonitor.h +++ b/inc/FBaseRtMonitor.h @@ -41,11 +41,11 @@ class _MonitorImpl; * * @final This class is not intended for extension. * - * The %Monitor class represents a monitor. %Monitor is a synchronization mechanism that provides acquire/release semantics by Enter() / Exit() as well as wait/notify semantics by Wait() / Notify() / NotifyAll(). + * The %Monitor class represents a monitor. A %Monitor is a synchronization mechanism that provides acquire and release semantics by Enter() and Exit() as well as wait and notify semantics by Wait(), Notify(), and NotifyAll(). * * For more information on the class features, see Monitor. * - * The following examples demonstrates how to use the %Monitor class. In the examples, 2 classes, Consumer and Producer, share a space. + * The following examples demonstrates how to use the %Monitor class. In the examples, two classes, Consumer and Producer, share a space. * Producer writes some data to this space, and Consumer reads it. Consumer and Producer run simultaneously. * Consumer must not miss the data which Producer writes. In this case, Consumer and Producer share the monitor. * Producer notifies Consumer that its writing action is done. Consumer waits for this notification, and reads the data after receiving it. @@ -287,39 +287,39 @@ public: * @since 2.0 * * @return An error code - * @exception E_SUCCESS The method is successful. + * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_SYSTEM A system error has occurred. + * @exception E_SYSTEM A system error has occurred. */ result Construct(void); /** - * Acquires a lock for a monitor. @n - * Semantically, this method declares the beginning of the critical region for the monitor. This region + * Acquires a lock for the monitor. @n + * Semantically, the %Enter() method declares the beginning of the critical region for the monitor. This region * ends with the Exit() method. * * @since 2.0 * * @return An error code - * @exception E_SUCCESS The method is successful in acquiring the lock. + * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @remarks This method will block if called on already locked monitor object until monitor becomes available. + * @remarks This method blocks if called on an already locked monitor object until the monitor becomes available. * @see Exit() */ result Enter(void); /** - * Releases a lock for a monitor. @n + * Releases the lock for the monitor. @n * Semantically, it declares the ending of the critical region for the monitor that begins with * the Enter() method. * * @since 2.0 * * @return An error code - * @exception E_SUCCESS The method is successful in releasing the lock. + * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @remarks This method should be called only after acquiring lock by Enter() call + * @remarks This method should be called only after acquiring the lock by the Enter() call. * @see Enter() */ result Exit(void); @@ -334,7 +334,7 @@ public: * @return An error code * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @remarks This method should be called only after acquiring lock by Enter() call + * @remarks This method should be called only after acquiring the lock by the Enter() call. * @see Notify() * @see NotifyAll() */ @@ -356,7 +356,7 @@ public: /** - * Notifies all waiting threads. + * Notifies all the waiting threads. * * @since 2.0 * diff --git a/inc/FBaseRtMonitorGuard.h b/inc/FBaseRtMonitorGuard.h index 76acb3f..fe2d86d 100644 --- a/inc/FBaseRtMonitorGuard.h +++ b/inc/FBaseRtMonitorGuard.h @@ -31,7 +31,7 @@ namespace Tizen { namespace Base { namespace Runtime /** * @class MonitorGuard -* @brief This class is the RAII style class for %Monitor class. +* @brief This class is the RAII style class for the Monitor class. * * @since 2.0 */ @@ -43,7 +43,7 @@ public: * * @since 2.0 * - * @param[in] m The %Monitor instance to be manipulated + * @param[in] m A Monitor instance to manipulate * @remarks The specific error code can be accessed using the GetLastResult() method. * @see Monitor::Enter() for detailed exceptions */ @@ -74,12 +74,12 @@ public: } /** - * Returns whether this instance owns the lock on the given monitor at constructor. + * Checks whether this instance owns the lock on the given monitor at constructor. * * @since 2.0 * * @return true if the lock is owned, @n - * false otherwise. + * else @c false */ bool IsEntered(void) const { @@ -87,8 +87,8 @@ public: } /** - * Returns whether this instance owns the lock on the given monitor at constructor. @n - * Have same effects to calling IsEntered(). + * Checks whether this instance owns the lock on the given monitor at constructor. @n + * This method has the same effects when calling IsEntered(). * * @since 2.0 */ diff --git a/inc/FBaseRtMutex.h b/inc/FBaseRtMutex.h index 49cca8a..c9bb61b 100755 --- a/inc/FBaseRtMutex.h +++ b/inc/FBaseRtMutex.h @@ -34,8 +34,8 @@ namespace Tizen { namespace Base { namespace Runtime /** * @struct NonRecursiveMutexTag * - * This struct is used only for providing the non-recursive type of mutex. - * A non-recursive mutex is a mutex that can not be acquired multiple times by the locking thread. It returns an exception if the locking thread tries to lock the same mutex. + * This struct is used only for providing the non-recursive type of the mutex. + * A non-recursive mutex is a mutex that cannot be acquired multiple times by the locking thread. It returns an exception if the locking thread tries to lock the same mutex. * * @since 2.1 * @@ -135,14 +135,14 @@ public: /** * Creates an unnamed mutex which is a recursive mutex that can be acquired multiple times by the locking thread. - * It keeps the number of getting locked and you must unlock it the same number of times. + * It keeps the number of locks and you must unlock it the same number of times. * * @since 2.0 * - * @return An error code - * @exception E_SUCCESS The method is successful. + * @return An error code + * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_SYSTEM A system error has occurred. + * @exception E_SYSTEM A system error has occurred. */ result Create(void); @@ -151,7 +151,7 @@ public: * * @since 2.1 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. */ @@ -159,15 +159,15 @@ public: /** * Creates a named mutex which is a recursive mutex that can be acquired multiple times by the locking thread. - * It keeps the number of getting locked and you must unlock it the same number of times. @n + * It keeps the number of locks and you must unlock it the same number of times. @n * If a mutex with the specified name already exists, this creates a mutex which references that particular mutex. * * @since 2.0 * - * @return An error code + * @return An error code * @param[in] name The name of the mutex * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_MEMORY The memory is insufficient. + * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. */ result Create(const Tizen::Base::String& name); @@ -177,10 +177,10 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. - * @exception E_SYSTEM A system error has occurred. - * @remarks This method should be called only after acquiring lock by Acquire()/ TryToAcquire() call + * @exception E_SYSTEM A system error has occurred. + * @remarks This method should be called only after acquiring a lock by calling Acquire() or TryToAcquire(). */ result Release(void); @@ -191,24 +191,24 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @remarks This method will block if called on already locked monitor object until mutex becomes available. + * @remarks This method blocks if called on an already locked monitor object until the mutex becomes available. */ result Acquire(void); /** * Tries to acquire the mutex if it is not acquired. @n - * If the mutex is already acquired by another thread, E_OBJECT_LOCKED is returned. + * If the mutex is already acquired by another thread, @c E_OBJECT_LOCKED is returned. * * @since 2.0 * - * @return An error code - * @exception E_SUCCESS The method is successful. - * @exception E_OBJECT_LOCKED The mutex is already locked. - * @exception E_SYSTEM A system error has occurred. - * @remarks This method will block if called on already locked monitor object until mutex becomes available. + * @return An error code + * @exception E_SUCCESS The method is successful. + * @exception E_OBJECT_LOCKED The mutex is already locked. + * @exception E_SYSTEM A system error has occurred. + * @remarks This method blocks if called on an already locked monitor object until the mutex becomes available. */ result TryToAcquire(void); diff --git a/inc/FBaseRtMutexGuard.h b/inc/FBaseRtMutexGuard.h index 23d7d9f..f0a428a 100644 --- a/inc/FBaseRtMutexGuard.h +++ b/inc/FBaseRtMutexGuard.h @@ -32,11 +32,11 @@ namespace Tizen { namespace Base { namespace Runtime /** * @class MutexGuard -* @brief This class is the RAII style class for %Mutex class. +* @brief This class is the RAII style class for the %Mutex class. * * @since 2.0 * -* The following example demonstrates how to use this %MutexGuard class +* The following example demonstrates how to use the %MutexGuard class * * @code * @@ -179,7 +179,7 @@ public: * * @since 2.0 * - * @param[in] m The %Mutex instance to be manipulated + * @param[in] m A %Mutex instance to manipulate * @remarks The specific error code can be accessed using the GetLastResult() method. * @see Mutex::Acquire() for detailed exceptions */ @@ -195,7 +195,7 @@ public: * * @since 2.0 * - * @param[in] m The %Mutex instance to be manipulated + * @param[in] m A %Mutex instance to be manipulated * @remarks The specific error code can be accessed using the GetLastResult() method. * @see Mutex::TryToAcquire() for detailed exceptions */ @@ -207,7 +207,7 @@ public: } /** - * This destructor releases the lock if acquired when going out of a scope + * This destructor releases the lock if acquired when going out of the scope * * @since 2.0 * @@ -220,12 +220,12 @@ public: } /** - * Returns whether this instance owns the lock on the given mutex at constructor. + * Checks whether this instance owns the lock on the given mutex at constructor. * * @since 2.0 * - * @return true if the lock is owned, @n - * false otherwise. + * @return @c true if the lock is owned, @n + * else @c false */ bool IsLocked(void) const { @@ -233,8 +233,8 @@ public: } /** - * Returns whether this instance owns the lock on the given mutex at constructor. @n - * Have same effects to calling IsLocked(). + * Checks whether this instance owns the lock on the given mutex at constructor. @n + * Has the same effects as calling IsLocked(). * * @since 2.0 */ @@ -244,11 +244,11 @@ public: } /** - * Acquires the lock manually on the given mutex at constructor in a blocking way + * Acquires the lock manually on the given mutex at constructor in a blocking way. * * @since 2.0 * - * @return An error code. + * @return An error code * @see Mutex::Acquire() for detailed exceptions */ result Lock(void) @@ -261,7 +261,7 @@ public: * * @since 2.0 * - * @return An error code. + * @return An error code * @see Mutex::TryToAcquire() for detailed exceptions */ result TryToLock(void) @@ -274,7 +274,7 @@ public: * * @since 2.0 * - * @return An error code. + * @return An error code * @see Mutex::Release() for detailed exceptions */ result Unlock(void) diff --git a/inc/FBaseRtSemaphore.h b/inc/FBaseRtSemaphore.h index ff71c2c..0bd67b4 100644 --- a/inc/FBaseRtSemaphore.h +++ b/inc/FBaseRtSemaphore.h @@ -31,14 +31,14 @@ namespace Tizen { namespace Base { namespace Runtime { /** * @class Semaphore - * @brief This class represents semaphore, a type of synchronization mechanisms. It can provide the acquiring semantics. @n + * @brief This class represents a semaphore, that is, a type of synchronization mechanism. It can provide the acquiring semantics. @n * * @since 2.0 * * @final This class is not intended for extension. * * The %Semaphore class represents a semaphore; a type of synchronization mechanism. - * It can provide the acquiring semantics. The semaphore allows the N threads to acquire the semaphore simultaneously. + * It can provide the acquiring semantics. The semaphore allows N threads to acquire the semaphore simultaneously. * * For more information on the class features, see Mutex and Semaphore. * @@ -111,12 +111,12 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @param[in] count The number of threads that can acquire the semaphore simultaneously @n * If the count is @c 1, then it is the same as a mutex. * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c count is less than @c 0. - * @exception E_OUT_OF_MEMORY The memory is insufficient. + * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. */ result Create(int count = 1); @@ -128,12 +128,12 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @param[in] name The name of the semaphore * @param[in] count The number of threads that can acquire the semaphore simultaneously * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c count is less than @c 0. - * @exception E_OUT_OF_MEMORY The memory is insufficient. + * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM A system error has occurred. */ result Create(const Tizen::Base::String& name, int count = 1); @@ -144,24 +144,25 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @param[in] timeout The period during which the thread tries to acquire the semaphore * @exception E_SUCCESS The method is successful. - * @exception E_TIMEOUT The operation cannot be completed within the specified time period. @n - * The method has failed to acquire the semaphore because the given time has elapsed. + * @exception E_TIMEOUT Either of the following conditions has occurred: + * - The operation cannot be completed within the specified time period. + * - The method has failed to acquire the semaphore because the given time has elapsed. * @exception E_SYSTEM A system error has occurred. */ result Acquire(long timeout = INFINITE); /** * Tries to acquire the semaphore. @n - * If the semaphore is already acquired by another thread, E_OBJECT_LOCKED is returned. + * If the semaphore is already acquired by another thread, @c E_OBJECT_LOCKED is returned. * * @since 2.0 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. - * @exception E_OBJECT_LOCKED The semaphore is already locked. + * @exception E_OBJECT_LOCKED The semaphore is already locked. * @exception E_SYSTEM A system error has occurred. */ result TryToAcquire(void); @@ -171,7 +172,7 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. */ diff --git a/inc/FBaseRtSemaphoreGuard.h b/inc/FBaseRtSemaphoreGuard.h index 074da8b..9ff5625 100644 --- a/inc/FBaseRtSemaphoreGuard.h +++ b/inc/FBaseRtSemaphoreGuard.h @@ -32,7 +32,7 @@ namespace Tizen { namespace Base { namespace Runtime /** * @class SemaphoreGuard -* @brief This class is the RAII style class for %Semaphore class. +* @brief This class is the RAII style class for the %Semaphore class. * * @since 2.0 */ @@ -40,14 +40,14 @@ class SemaphoreGuard { public: /** - * This constructor acquires a semaphore count in a blocking way. - * - * @since 2.0 - * - * @param[in] s The %Semaphore instance to be manipulated - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @see Semaphore::Acquire() for detailed exceptions - */ + * This constructor acquires a semaphore count in a blocking way. + * + * @since 2.0 + * + * @param[in] s A Semaphore instance to manipulate + * @remarks The specific error code can be accessed using the GetLastResult() method. + * @see Semaphore::Acquire() for detailed exceptions + */ SemaphoreGuard(Semaphore& s) : __s(s) , __acquired(false) @@ -56,14 +56,14 @@ public: } /** - * This constructor acquires a semaphore count in a non-blocking way. - * - * @since 2.0 - * - * @param[in] s The %Semaphore instance to be manipulated - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @see Semaphore::TryToAcquire() for detailed exceptions - */ + * This constructor acquires a semaphore count in a non-blocking way. + * + * @since 2.0 + * + * @param[in] s A Semaphore instance to manipulate + * @remarks The specific error code can be accessed using the GetLastResult() method. + * @see Semaphore::TryToAcquire() for detailed exceptions + */ SemaphoreGuard(Semaphore& s, TryTag) : __s(s) , __acquired(false) @@ -72,76 +72,76 @@ public: } /** - * This destructor releases the acquired semaphore count when going out of a scope - * - * @since 2.0 - * - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @see Semaphore::Release() for detailed exceptions - */ + * This destructor releases the acquired semaphore count when going out of the scope + * + * @since 2.0 + * + * @remarks The specific error code can be accessed using the GetLastResult() method. + * @see Semaphore::Release() for detailed exceptions + */ ~SemaphoreGuard(void) { SetLastResult(Release()); } /** - * Returns whether this instance owns a semaphore count on the given semaphore at constructor. - * - * @since 2.0 - * - * @return true if a semaphore is owned, @n - * false otherwise. - */ + * Checks whether this instance owns a semaphore count on the given semaphore at constructor. + * + * @since 2.0 + * + * @return @c true if a semaphore is owned, @n + * else @c false + */ bool IsAcquired(void) const { return __acquired; } /** - * Returns whether this instance owns a semaphore count on the given semaphore at constructor. @n - * Have same effects to calling IsAcquired(). - * - * @since 2.0 - */ + * Checks whether this instance owns a semaphore count on the given semaphore at constructor. @n + * Has the same effects as calling IsAcquired(). + * + * @since 2.0 + */ operator bool() const { return IsAcquired(); } /** - * Acquires a semaphore count manually on the given semaphore at constructor in a blocking way - * - * @since 2.0 - * - * @return An error code. - * @see Semaphore::Acquire() for detailed exceptions - */ + * Acquires a semaphore count manually on the given semaphore at constructor in a blocking way. + * + * @since 2.0 + * + * @return An error code + * @see Semaphore::Acquire() for detailed exceptions + */ result Acquire(void) { return SetAcquiredAndReturn(__s.Acquire()); } /** - * Acquires a semaphore count manually on the given semaphore at constructor in a non-blocking way - * - * @since 2.0 - * - * @return An error code. - * @see Semaphore::TryToAcquire() for detailed exceptions - */ + * Acquires a semaphore count manually on the given semaphore at constructor in a non-blocking way. + * + * @since 2.0 + * + * @return An error code + * @see Semaphore::TryToAcquire() for detailed exceptions + */ result TryToAcquire(void) { return SetAcquiredAndReturn(__s.TryToAcquire()); } /** - * Releases the acquired semaphore count manually - * - * @since 2.0 - * - * @return An error code. - * @see Semaphore::Release() for detailed exceptions - */ + * Releases the acquired semaphore count manually + * + * @since 2.0 + * + * @return An error code + * @see Semaphore::Release() for detailed exceptions + */ result Release(void) { result r = E_SUCCESS; diff --git a/inc/FBaseRtThread.h b/inc/FBaseRtThread.h index a27a4af..0a4770d 100644 --- a/inc/FBaseRtThread.h +++ b/inc/FBaseRtThread.h @@ -61,8 +61,8 @@ namespace Tizen { namespace Base { namespace Runtime */ enum ThreadType { - THREAD_TYPE_WORKER = 0, /**< @if OSPDEPREC The worker thread mode @endif */ - THREAD_TYPE_EVENT_DRIVEN, /**< @if OSPDEPREC The event-driven thread mode @endif */ + THREAD_TYPE_WORKER = 0, /**< @if OSPDEPREC The worker thread mode @endif */ + THREAD_TYPE_EVENT_DRIVEN, /**< @if OSPDEPREC The event-driven thread mode @endif */ THREAD_TYPE_MAIN // This enum value is for internal use only. Using this enum value can cause behavioral, // security-related, and consistency-related issues in the application. // The main thread mode @@ -92,7 +92,7 @@ enum ThreadPriority * @remarks This class supports only worker threads. For event-driven threads, use the EventDrivenThread class. * * The %Thread class is the fundamental class for the asynchronous execution of a thread. - * A Tizen native application can execute several threads during its operation from the multi-threading view. + * A %Tizen native application can execute several threads during its operation from the multi-threading view. * * For more information on the class features, see Thread. * @@ -169,10 +169,11 @@ public: * * @return An error code * @param[in] milliSeconds The time, in milliseconds, for which to suspend the execution @n - * A value of zero causes the thread to relinquish the remainder of its time - * slice to any other thread that is ready to run. The time cannot be negative. + * The value of zero causes the thread to relinquish the remainder of its time + * slice to any other thread that is ready to run @n + * The time cannot be negative. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A negative time value is passed. + * @exception E_INVALID_ARG A negative time value has been passed. */ static result Sleep(long milliSeconds); @@ -201,7 +202,7 @@ public: static result Exit(int exitCode = 0x00); /** - * Gets the pointer of the currently running %Thread instance. + * Gets a pointer of the currently running %Thread instance. * * @since 2.0 * @@ -224,7 +225,7 @@ public: * Initializes this instance of %Thread with the specified thread type, stack size, and priority. * * @brief [Deprecated] - * @deprecated This method is deprecated because the %Thread class does not support event-driven thread any more. Instead, use the EventDrivenThread class instead. + * @deprecated This method is deprecated because the %Thread class does not support event-driven threads any more. Instead, use the EventDrivenThread class. * * @since 2.0 * @@ -233,7 +234,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @endif */ @@ -244,7 +245,7 @@ public: * Initializes this instance of %Thread with the specified name, thread type, stack size, and priority. * * @brief [Deprecated] - * @deprecated This method is deprecated because the %Thread class does not support event-driven thread any more. Instead, use the EventDrivenThread class instead. + * @deprecated This method is deprecated because the %Thread class does not support event-driven threads any more. Instead, use the EventDrivenThread class. * * @since 2.0 * @@ -254,7 +255,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @endif */ @@ -270,7 +271,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID); @@ -285,7 +286,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(const Tizen::Base::String& name, @@ -301,7 +302,7 @@ public: * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(IRunnable& target, long stackSize = DEFAULT_STACK_SIZE, ThreadPriority priority = THREAD_PRIORITY_MID); @@ -311,13 +312,13 @@ public: * * @since 2.0 * - * @return An error code - * @param[in] name The name of the thread + * @return An error code + * @param[in] name The name of the thread * @param[in] target An instance of IRunnable * @param[in] stackSize The thread stack size * @param[in] priority The thread priority * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG An invalid argument is passed. + * @exception E_INVALID_ARG A specified input parameter is invalid. * @exception E_OUT_OF_MEMORY The memory is insufficient. */ result Construct(const Tizen::Base::String& name, IRunnable& target, @@ -333,13 +334,13 @@ public: virtual ~Thread(void); /** - * Waits until the thread execution is terminated. + * Joins after the thread execution is terminated. * * @since 2.0 * * @return An error code * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_OPERATION An other thread is calling this method. + * @exception E_INVALID_OPERATION Another thread is calling this method. * @exception E_SYSTEM A system error has occurred. */ result Join(void); @@ -366,8 +367,8 @@ public: * @since 2.0 * * @return An error code - * @exception E_SUCCESS The method is successful. - * @exception E_SYSTEM A system error has occurred. + * @exception E_SUCCESS The method is successful. + * @exception E_SYSTEM A system error has occurred. * @remarks This is only available for event-driven threads. * @endif */ @@ -375,7 +376,7 @@ public: /** * Called when the thread is started without the IRunnable instance. @n - * The body for thread execution is specified by inheriting the %Thread class and implementing this method. + * The body for the thread execution is specified by inheriting the %Thread class and implementing this method. * * @since 2.0 * @@ -385,7 +386,7 @@ public: virtual Tizen::Base::Object* Run(void); /** - * Gets an exit code of the thread which is given by calling the Exit() method. + * Gets the exit code of the thread which is given by calling the Exit() method. * * @since 2.0 * @@ -403,7 +404,7 @@ public: * @since 2.0 * * @return The name of the thread - * @exception E_SUCCESS The method is successful. + * @exception E_SUCCESS The method is successful. */ const Tizen::Base::String& GetName(void) const; @@ -420,8 +421,8 @@ public: * @since 2.0 * * @return @c true if this thread can be run, @n - * else @c false - * @remarks You can initialize the event or event listener in this method for running this + * else @c false + * @remarks The event or event listener in this method can be initialized for running this * thread in an event-driven mode. * @endif */ @@ -435,7 +436,7 @@ public: * @deprecated This method is deprecated because the %Thread class does not support event-driven threads. * @since 2.0 * - * @remarks You can finalize the event or event listener in this method for running this + * @remarks The event or event listener in this method can be finalized for running this * thread in an event-driven mode. * * @endif @@ -452,8 +453,8 @@ public: * @since 2.0 * * @return An error code - * @param[in] requestId The user-defined event Id - * @param[in] pArgs A pointer to a list of arguments + * @param[in] requestId The user-defined event ID + * @param[in] pArgs A pointer to the list of arguments * @exception E_SUCCESS The method is successful. * @exception E_INVALID_OPERATION The thread is not an event-driven thread. * @@ -472,8 +473,8 @@ public: * * @since 2.0 * - * @param[in] requestId The user-defined event Id - * @param[in] pArgs A pointer to a list of arguments + * @param[in] requestId The user-defined event ID + * @param[in] pArgs A pointer to the list of arguments * @see SendUserEvent() * @endif */ diff --git a/inc/FBaseRtTimer.h b/inc/FBaseRtTimer.h index 1008b0d..a388603 100644 --- a/inc/FBaseRtTimer.h +++ b/inc/FBaseRtTimer.h @@ -38,10 +38,10 @@ namespace Tizen { namespace Base { namespace Runtime * @since 2.0 * * The %Timer class can activate the timer and notify the listeners. - * It supports relative time and provides both repeatable and non-repeatable timer. - * Because Timer is handled by event-driven way, when the main loop gets blocked, even if the time is expired, the listener cannot get notified. - * Once the target goes into sleep mode, Timer does not work properly because the main loop gets stopped. - * You can use Alarm on behalf of Timer for sleep mode. + * It supports the relative time and provides both repeatable and non-repeatable timers. + * Because %Timer is handled in an event-driven way, when the main loop gets blocked, even if the time is expired, the listener cannot get notified. + * Once the target goes into the sleep mode, %Timer does not work properly because the main loop gets stopped. + * You can use Alarm on behalf of the %Timer for the sleep mode. * For more information on the class features, see Timer. * The following example demonstrates how to use the %Timer class. * @@ -141,10 +141,10 @@ public: * @since 2.0 * * @return An error code - * @param[in] listener The event listener - * @exception E_SUCCESS The method is successful. + * @param[in] listener The event listener + * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_SYSTEM A system error has occurred. + * @exception E_SYSTEM A system error has occurred. */ result Construct(ITimerEventListener& listener); @@ -158,45 +158,45 @@ public: * @since 2.0 * * @if OSPCOMPAT - * @compatibility This method has compatibility issues with %Tizen API versions @b prior @b to @b 2.1. @n - * For more information, see @ref CompTimerStartPage "here". + * @compatibility This method has compatibility issues with Tizen API versions @b prior @b to @b 2.1. @n + * For more information, see @ref CompTimerStartPage "here". * @endif * * @return An error code - * @param[in] timeout A timeout interval in milliseconds - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid. - * @exception E_INVALID_STATE The timer is in an invalid state for start. - * @exception E_SYSTEM A system error has occurred. - * @remarks Once the timer has been started, it cannot be started again until expired. + * @param[in] timeout The timeout interval in milliseconds + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified input parameter is invalid. + * @exception E_INVALID_STATE The timer cannot start as it is in an invalid state. + * @exception E_SYSTEM A system error has occurred. + * @remarks Once the timer has been started, it cannot be started again until it has expired. * @see Cancel() */ result Start(int timeout); /** - * @page CompTimerStartPage Compatibility for Start(int timeout) - * @section CompTimerStartPageIssueSection Issues - * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n - * -# The method returns E_INVALID_ARG if timeout is equal to zero. - * - * @section CompTimerStartPageSolutionSection Resolutions - * The issue mentioned above is resolved in %Tizen API version 2.1, and it is recommended to use %Tizen API version 2.1 or above. - * -# In case of zero, Timer sets timeout to the best-effort minimum interval without returning E_INVALID_ARG. - */ + * @page CompTimerStartPage Compatibility for Start(int timeout) + * @section CompTimerStartPageIssueSection Issues + * Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n + * -# The method returns @c E_INVALID_ARG if timeout is equal to zero. + * + * @section CompTimerStartPageSolutionSection Resolutions + * The issue mentioned above is resolved in Tizen API version 2.1, and it is recommended to use Tizen API version 2.1 or above. + * -# In case of zero, %Timer sets the timeout to the best possible minimum interval without returning @c E_INVALID_ARG. + */ /** * Starts the timer. @n - * The timer is expired repeatedly until canceled. + * The timer expires repeatedly until it is cancelled. * * @since 2.0 * * @return An error code - * @param[in] interval A timeout interval in milliseconds - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid. - * @exception E_INVALID_STATE The timer is in an invalid state for start. - * @exception E_SYSTEM A system error has occurred. - * @remarks To stop timer expiration or restart a timer, the timer must be canceled. + * @param[in] interval The timeout interval in milliseconds + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG The specified input parameter is invalid. + * @exception E_INVALID_STATE The timer cannot start as it is in an invalid state. + * @exception E_SYSTEM A system error has occurred. + * @remarks To stop the timer expiration or restart the timer, the timer must be cancelled. * @see Cancel() */ result StartAsRepeatable(int interval); @@ -206,10 +206,11 @@ public: * * @since 2.0 * - * @return An error code + * @return An error code * @exception E_SUCCESS The method is successful. * @exception E_SYSTEM A system error has occurred. - * @remarks The started timer can be canceled when it does not get expired. If the timer was already expired, this method also returns E_SUCCESS which affects the same manner when canceled normally. + * @remarks The started timer can be cancelled when it does not get expired. @n + * If the timer has already expired, this method also returns @c E_SUCCESS which causes the same effect as when cancelled normally. */ result Cancel(void); diff --git a/inc/FBaseRtTypes.h b/inc/FBaseRtTypes.h index 8cfe3d3..d0dc55b 100644 --- a/inc/FBaseRtTypes.h +++ b/inc/FBaseRtTypes.h @@ -16,7 +16,7 @@ /** * @file FBaseRtTypes.h - * @brief This is the header file for the types in the Runtime package. + * @brief This is the header file for the types in the %Runtime package. * * This header file defines the types in the Runtime package. */ @@ -45,9 +45,9 @@ enum TimerStatus /** * @struct TryTag -* @brief This struct is used only for supporting non-blocking acquisition of a resource. +* @brief This struct is used only for supporting the non-blocking acquisition of a resource. * -* The %TryTag struct is used for just discriminating between blocking and non-blocking acquisition +* The %TryTag struct is used for just discriminating between the blocking and non-blocking acquisitions * of a resource. So, the definition is empty. * * @since 2.0 @@ -61,7 +61,7 @@ struct TryTag }; /** -* @brief Used only for just discriminating between blocking and non-blocking acquisition. +* @brief Used only for discriminating between the blocking and non-blocking acquisitions. * * @code * Mutex m; diff --git a/inc/FBaseRtWaitingLoop.h b/inc/FBaseRtWaitingLoop.h index b8f44a4..06cb7f4 100755 --- a/inc/FBaseRtWaitingLoop.h +++ b/inc/FBaseRtWaitingLoop.h @@ -33,7 +33,7 @@ namespace Tizen { namespace Base { namespace Runtime class IWaitingLoopCondition; /* * @class WaitingLoop - * @brief This class allows developers to make the current thread wait for callback events. This class should be used only for test codes and don't use this class for commercial applications + * @brief This class allows developers to make the current thread wait for callback events. This class should be used only for test codes and not for commercial applications. * @since 2.0 * * @final This class is not intended for extension. @@ -43,13 +43,14 @@ class _OSP_EXPORT_ WaitingLoop { public: /* - * Gets the WaitingLoop instance. + * Gets a pointer to the %WaitingLoop instance. * * @since 2.0 * - * @return A pointer to the WaitingLoop instance, @n + * @return A pointer to a WaitingLoop instance, @n * else @c null if it fails - * @remarks Once the WaitingLoop instance has been created, you must not use the instance between threads. Especially, the methods for waiting should be called on the thread you get the instance at first time. + * @remarks Once the WaitingLoop instance has been created, the instance between the threads must not be used. @n + * Especially, the methods that are waiting should be called on the thread where the instance is obtained for the first time. */ static WaitingLoop* GetInstance(void); @@ -58,13 +59,13 @@ public: * * @since 2.0 * - * @param[in] timeout The timeout period in milliseconds - * @exception E_SUCCESS The method is successful. - * @exception E_TIMEOUT The time is expired. - * @exception E_INVALID_STATE The waiting loop has already been waiting on a callback event. In order to wait again, you must quit the waiting loop. - * @remarks The timeout set to min(timeout, maximum), where the maximum is set using SetMaxTimeoutForWaiting(). + * @param[in] timeout The timeout period in milliseconds + * @exception E_SUCCESS The method is successful. + * @exception E_TIMEOUT The time has expired. + * @exception E_INVALID_STATE The waiting loop has already been waiting on a callback event. @n + * In order to wait again, quit the waiting loop. + * @remarks The timeout is set to min(timeout, maximum), where the maximum is set using SetMaxTimeoutForWaiting(). * @see Notify() - * @see SetMaxTimoutForWaiting() */ result Wait(int timeout); @@ -73,32 +74,35 @@ public: * * @since 2.0 * - * @param[in] condition The expiring condition - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_STATE The waiting loop has already been waiting on a callback event. In order to wait again, you must quit the waiting loop. - * @remarks In order to use this method correctly, you have to implement a class inheriting from %IWaitingLoopCondition. + * @param[in] condition The expiring condition + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_STATE The waiting loop has already been waiting on a callback event. @n + * In order to wait again, quit the waiting loop. + * @remarks In order to use this method correctly, you have to implement a class inheriting from IWaitingLoopCondition. */ result Wait(IWaitingLoopCondition& condition); /* - * Starts the waiting loop and waits until either the expiring condition occurs or the time is expired. + * Starts the waiting loop and waits until either the expiring condition occurs or the time expires. * * @since 2.0 * - * @param[in] timeout The timeout period in milliseconds - * @param[in] condition The expiring condition - * @exception E_TIMEOUT The time is expired. - * @exception E_INVALID_STATE The waiting loop is waiting on a thread. In order to wait again, you must quit the waiting loop. - * @remarks If the timeout is over the maximum, the expired time goes together with the maximum timeout. In order to use this method correctly, you have to implement a class inheriting from %IWaitingLoopCondition interface + * @param[in] timeout The timeout period in milliseconds + * @param[in] condition The expiring condition + * @exception E_TIMEOUT The time has expired. + * @exception E_INVALID_STATE The waiting loop is waiting on a thread. @n + * In order to wait again, quit the waiting loop. + * @remarks If the timeout has crossed the maximum value, the expired time goes along with the maximum timeout. @n + * In order to use this method correctly, implement a class inheriting from the IWaitingLoopCondition interface */ result Wait(int timeout, IWaitingLoopCondition& condition); /* - * Notify the waiting thread that the related callback has completed the job. + * Notifies the waiting thread that the related callback has completed the job. * * @since 2.0 * - * @remarks This method is recommended to use when the waiting condition is not explicitly specified with Wait(). + * @remarks This method is recommended when the waiting condition is not explicitly specified by Wait(). */ void Notify(void); @@ -108,8 +112,8 @@ public: * @since 2.0 * * @param[in] timeout The timeout period in milliseconds - * else @c false - * @remarks If the timeout is considered as a small number, it will be replaced with the specified number provided by platform. + * else @c false + * @remarks If the timeout is considered as a small number, it is replaced with the specified number provided by the platform. */ static void SetMaxTimeoutForWaiting(int timeout); -- 2.7.4