Commit 284e0c23 authored by Éric Thiébaut's avatar Éric Thiébaut
Browse files

Update doc.

parent 2b7d33ac
......@@ -161,9 +161,9 @@ extern uint32_t tao_remote_camera_get_type(
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return The identifier of the remote camera data, `TAO_BAD_SHMID` if @a cam
* is `NULL`. Whatever the result, this getter function leaves the
* caller's last error unchanged.
* @return The shared memory identifier of the remote camera data,
* `TAO_BAD_SHMID` if @a cam is `NULL`. Whatever the result, this
* getter function leaves the caller's last error unchanged.
*
* @see tao_remote_camera_attach.
*/
......
......@@ -20,7 +20,7 @@
TAO_BEGIN_DECLS
/**
* @defgroup RWLockedObjects R/w locked objects
* @defgroup RWLockedObjects Read/write locked objects
*
* @ingroup ParallelProgramming
*
......@@ -38,29 +38,151 @@ TAO_BEGIN_DECLS
* @brief Opaque structure for a read/write locked object.
*
* Read/write locked objects are shared objects (see @ref tao_shared_object)
* which implement read/write lock.
* implementing a read/write lock. Such objects are shared objects whose
* resources are controlled for read-only or read-write access. At any time,
* there can be any number of readers with read-only access and no writers, or
* a single writer with read-write access and no readers.
*
* @see tao_rwlocked_object_.
*/
typedef struct tao_rwlocked_object_ tao_rwlocked_object;
/**
* @brief Create a new read/write locked object.
*
* This function creates a new read/write locked object stored in shared
* memory. The new object is initially attached to the address space of the
* caller, other processes may access the object by calling
* tao_rwlocked_object_attach(). When the object is no longer used by the
* caller, the caller is responsible of calling tao_rwlocked_object_detach() to
* detach the object from its address space.
*
* The remaining bytes after the basic object information are all set to zero.
*
* @param type Type identifier of the object.
*
* @param size Total number of bytes to allocate.
*
* @param flags Permissions granted to the group and to the others. At least,
* read and write access (that is bits `S_IRUSR` and `S_IWUSR`)
* are granted for the caller. Unless bit @ref TAO_PERSISTENT is
* set in `flags`, the shared memory backing the storage of the
* shared data will be destroyed upon last detach.
*
* @return The address of the new object in the address space of the caller;
* `NULL` in case of failure.
*
* @see tao_shared_object_create(), tao_rwlocked_object_attach().
*/
extern tao_rwlocked_object* tao_rwlocked_object_create(
uint32_t type,
size_t size,
unsigned flags);
/**
* @brief Attach an existing read/write locked object to the address space of
* the caller.
*
* This function attaches an existing read/write locked object to the address
* space of the caller. As a result, the number of attachments on the returned
* object is incremented by one. When the object is no longer used by the
* caller, the caller is responsible of calling tao_rwlocked_object_detach() to
* detach the object from its address space, decrement its number of
* attachments by one and eventually free the shared memory associated with the
* object.
*
* In principle, the same process may attach a read/write locked object more
* than once but each attachment, due to tao_rwlocked_object_attach() or to
* tao_rwlocked_object_create(), should be matched by a
* tao_rwlocked_object_detach() with the corresponding address in the caller's
* address space.
*
* @param shmid Shared memory identifier.
*
* @return The address of the read/write locked object in the address space of
* the caller; `NULL` in case of failure. Even tough the arguments are
* correct, an error may arise if the object has been destroyed before
* attachment completes.
*
* @see tao_rwlocked_object_detach().
*/
extern tao_rwlocked_object* tao_rwlocked_object_attach(
tao_shmid shmid);
/**
* @brief Detach a read/write locked object from the address space of the
* caller.
*
* This function detaches a read/write locked object from the address space of
* the caller and decrements the number of attachments of the read/write locked
* object. If the number of attachements reaches zero, the shared memory
* segment backing the storage of the object is destroyed (unless bit @ref
* TAO_PERSISTENT was set at object creation).
*
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*
* @see tao_rwlocked_object_attach().
*/
extern tao_status tao_rwlocked_object_detach(
tao_rwlocked_object* obj);
/**
* @brief Get the size of a read/write locked object.
*
* This function yields the number of bytes of shared memory occupied by the
* read/write locked object. The size is constant for the life of the object,
* it is thus not necessary to have locked the object to retrieve its
* identifier.
*
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return The number of bytes of the shared memory segment backing the storage
* of the read/write locked object, `0` if @a obj is `NULL`. Whatever
* the result, this getter function leaves the caller's last error
* unchanged.
*/
extern size_t tao_rwlocked_object_get_size(
const tao_rwlocked_object* obj);
/**
* @brief Get the type identifier of a read/write locked object.
*
* This function yields the identifier of the type of the read/write locked
* object. The type identifier is constant for the life of the object, it is
* thus not necessary to have locked the object to retrieve its identifier.
*
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return The type identifier of the read/write locked object, `0` if @a obj
* is `NULL`. Whatever the result, this getter function leaves the
* caller's last error unchanged.
*/
extern uint32_t tao_rwlocked_object_get_type(
const tao_rwlocked_object* obj);
/**
* @brief Get the shared memory identifier of a read/write locked object.
*
* This function yields the shared memory identifier of the read/write locked
* object. This value can be used by another process to attach to its address
* space the read/write locked object. The shared memory identifier is
* constant for the life of the object, it is thus not necessary to have locked
* the object to retrieve its identifier.
*
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return The identifier of the read/write locked object data, `TAO_BAD_SHMID`
* if @a obj is `NULL`. Whatever the result, this getter function
* leaves the caller's last error unchanged.
*
* @see tao_rwlocked_object_attach.
*/
extern tao_shmid tao_rwlocked_object_get_shmid(
const tao_rwlocked_object* obj);
......@@ -70,8 +192,8 @@ extern tao_shmid tao_rwlocked_object_get_shmid(
* This function unlocks a read/write locked object that has been successfully
* locked by the caller.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*/
......@@ -79,18 +201,18 @@ extern tao_status tao_rwlocked_object_unlock(
tao_rwlocked_object* obj);
/**
* @brief Lock a shared object for read-only access.
* @brief Lock a read/write locked object for read-only access.
*
* This function is similar to @ref tao_rdlock_rwlock except that it applies to
* a shared object. The object must be attached to the address space of the
* caller. In case of success, the caller is responsible for calling
* tao_rwlocked_object_unlock() to eventually release the lock.
* This function is similar to @ref tao_rwlock_rdlock except that it applies to
* a read/write locked object. The object must be attached to the address
* space of the caller. In case of success, the caller is responsible for
* calling tao_rwlocked_object_unlock() to eventually release the lock.
*
* @warning The same thread/process must not attempt to lock the same object
* more than once and should unlock it as soon as possible.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*/
......@@ -98,18 +220,18 @@ extern tao_status tao_rwlocked_object_rdlock(
tao_rwlocked_object* obj);
/**
* @brief Lock a shared object for read-write access.
* @brief Lock a read/write locked object for read-write access.
*
* This function is similar to @ref tao_wrlock_rwlock except that it applies to
* a shared object. The object must be attached to the address space of the
* This function is similar to @ref tao_rwlock_wrlock except that it applies to
* a read/write locked object. The object must be attached to the address space of the
* caller. In case of success, the caller is responsible for calling
* tao_rwlocked_object_unlock() to eventually release the lock.
*
* @warning The same thread/process must not attempt to lock the same object
* more than once and should unlock it as soon as possible.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*/
......@@ -117,20 +239,21 @@ extern tao_status tao_rwlocked_object_wrlock(
tao_rwlocked_object* obj);
/**
* @brief Attempt to lock a shared object for read-only access without
* blocking.
* @brief Attempt to lock a read/write locked object for read-only access
* without blocking.
*
* This function attempts to lock a shared object for read-only access. This
* function is similar to @ref tao_try_rdlock_rwlock except that it applies to
* a shared object. The object must be attached to the address space of the
* caller. In case of success, the caller is responsible for calling
* tao_rwlocked_object_unlock() to eventually release the lock.
* This function attempts to lock a read/write locked object for read-only
* access. This function is similar to @ref tao_rwlock_try_rdlock except that
* it applies to a read/write locked object. The object must be attached to
* the address space of the caller. In case of success, the caller is
* responsible for calling tao_rwlocked_object_unlock() to eventually release
* the lock.
*
* @warning The same thread/process must not attempt to lock the same object
* more than once and should unlock it as soon as possible.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_TIMEOUT if the object cannot be
* immediately locked; @ref TAO_ERROR in case of failure.
......@@ -139,20 +262,21 @@ extern tao_status tao_rwlocked_object_try_rdlock(
tao_rwlocked_object* obj);
/**
* @brief Attempt to lock a shared object for read-write access without
* blocking.
* @brief Attempt to lock a read/write locked object for read-write access
* without blocking.
*
* This function attempts to lock a shared object for read-write access. This
* function is similar to @ref tao_try_wrlock_rwlock except that it applies to
* a shared object. The object must be attached to the address space of the
* caller. In case of success, the caller is responsible for calling
* tao_rwlocked_object_unlock() to eventually release the lock.
* This function attempts to lock a read/write locked object for read-write
* access. This function is similar to @ref tao_rwlock_try_wrlock except that
* it applies to a read/write locked object. The object must be attached to
* the address space of the caller. In case of success, the caller is
* responsible for calling tao_rwlocked_object_unlock() to eventually release
* the lock.
*
* @warning The same thread/process must not attempt to lock the same object
* more than once and should unlock it as soon as possible.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @return @ref TAO_OK on success; @ref TAO_TIMEOUT if the object cannot be
* immediately locked; @ref TAO_ERROR in case of failure.
......@@ -167,8 +291,8 @@ extern tao_status tao_rwlocked_object_try_wrlock(
* This function behaves like @ref tao_rwlocked_object_rdlock but blocks no
* longer than a given number of seconds.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @param secs Maximum time to wait (in seconds). If this amount of time is
* very large, e.g. more than @ref TAO_MAX_TIME_SECONDS, the
......@@ -190,8 +314,8 @@ extern tao_status tao_rwlocked_object_timed_rdlock(
* This function behaves like @ref tao_rwlocked_object_wrlock but blocks no
* longer than a given number of seconds.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @param secs Maximum time to wait (in seconds). If this amount of time is
* very large, e.g. more than @ref TAO_MAX_TIME_SECONDS, the
......@@ -213,8 +337,9 @@ extern tao_status tao_rwlocked_object_timed_wrlock(
* This function behaves like @ref tao_rwlocked_object_rdlock but blocks no
* longer than a given time limit.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @param abstime Time limit (using `CLOCK_REALTIME` clock).
*
* @return @ref TAO_OK on success; @ref TAO_TIMEOUT if the lock cannot acquired
......@@ -231,8 +356,9 @@ extern tao_status tao_rwlocked_object_abstimed_rdlock(
* This function behaves like @ref tao_rwlocked_object_wrlock but blocks no
* longer than a given time limit.
*
* @param obj Pointer to a shared object attached to the address space of
* the caller.
* @param obj Pointer to a read/write locked object attached to the address
* space of the caller.
*
* @param abstime Time limit (using `CLOCK_REALTIME` clock).
*
* @return @ref TAO_OK on success; @ref TAO_TIMEOUT if the lock cannot acquired
......
......@@ -245,9 +245,9 @@ extern uint32_t tao_shared_object_get_type(
* @param obj Pointer to a shared object attached to the address space of
* the caller.
*
* @return The identifier of the shared object data, `TAO_BAD_SHMID` if @a obj
* is `NULL`. Whatever the result, this getter function leaves the
* caller's last error unchanged.
* @return The shared memory identifier of the shared object, `TAO_BAD_SHMID`
* if @a obj is `NULL`. Whatever the result, this getter function
* leaves the caller's last error unchanged.
*
* @see tao_shared_object_attach.
*/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment