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

Update doc.

parent cda19591
......@@ -110,6 +110,7 @@ extern tao_status tao_mutex_try_lock(
* given absolute time limit.
*
* @param mutex Pointer to the mutex to lock.
*
* @param abstime Absolute time limit for waiting.
*
* @return @ref TAO_OK if the lock has been locked by the caller before the
......@@ -165,6 +166,7 @@ extern tao_status tao_mutex_unlock(
* tao_mutex_initialize().
*
* @param mutex Pointer to the mutex to destroy.
*
* @param wait If the mutex is locked, this parameter specifies whether the
* function should block until the mutex is unlocked by its
* owner.
......@@ -214,6 +216,7 @@ typedef pthread_cond_t tao_cond;
* may be associated with the condition variable.
*
* @param cond Pointer to the condition variable to initialize.
*
* @param shared If true, require that the condition variable be accessible
* between processes; otherwise, the condition variable will be
* *private* (that is, only accessible by threads in the same
......@@ -253,7 +256,7 @@ extern tao_status tao_condition_signal(
tao_cond* cond);
/**
* Signal a condition variable to all waiting thread.
* Signal a condition variable to all waiting threads.
*
* This function behaves like tao_condition_signal() except that all threads
* waiting on the condition variable @a cond are restarted. Nothing happens,
......@@ -276,6 +279,7 @@ extern tao_status tao_condition_broadcast(
* returning to the calling thread, this function re-acquires the mutex.
*
* @param cond Address of the condition variable to wait on.
*
* @param mutex Address of the mutex associated with the condition variable.
*
* @return @ref TAO_OK on success, @ref TAO_ERROR in case of failure.
......@@ -294,8 +298,11 @@ extern tao_status tao_condition_wait(
* a given absolute time limit.
*
* @param cond Address of the condition variable to wait on.
*
* @param mutex Address of the mutex associated with the condition variable.
* @param abstime Absolute time limit for waiting.
*
* @param lim Absolute time limit with the same conventions as
* tao_get_current_time().
*
* @return @ref TAO_OK if the condition is signaled before the specified number
* of seconds; @ref TAO_TIMEOUT if timeout occured before; @ref
......@@ -307,7 +314,7 @@ extern tao_status tao_condition_wait(
extern tao_status tao_condition_abstimed_wait(
tao_cond* cond,
tao_mutex* mutex,
const tao_time* abstime);
const tao_time* lim);
/**
* Wait for a condition to be signaled without blocking longer than a relative
......@@ -317,9 +324,11 @@ extern tao_status tao_condition_abstimed_wait(
* some given duration.
*
* @param cond Address of the condition variable to wait on.
*
* @param mutex Address of the mutex associated with the condition variable.
* @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
*
* @param secs Maximum amount of time (in seconds). If this amount of time
* is very large, e.g. more than @ref TAO_MAX_TIME_SECONDS, the
* effect is the same as calling tao_condition_wait().
*
* @return @ref TAO_OK if the condition is signaled before the specified number
......@@ -385,6 +394,7 @@ typedef pthread_rwlock_t tao_rwlock;
* be associated with the read/write lock.
*
* @param lock Pointer to the read/write lock to initialize.
*
* @param shared If true, require that the read/write lock be accessible
* between processes; otherwise, the read/write lock will be
* *private* (that is, only accessible by threads in the same
......@@ -474,6 +484,7 @@ extern tao_status tao_rwlock_try_wrlock(
* blocking longer than a time limit.
*
* @param lock Pointer to the read/write lock.
*
* @param abstime Time limit (using `CLOCK_REALTIME` clock).
*
* @return @ref TAO_OK if successful; @ref TAO_TIMEOUT if the lock cannot
......@@ -489,6 +500,7 @@ extern tao_status tao_rwlock_abstimed_rdlock(
* blocking longer than a time limit.
*
* @param lock Pointer to the read/write lock.
*
* @param abstime Time limit (using `CLOCK_REALTIME` clock).
*
* @return @ref TAO_OK if successful; @ref TAO_TIMEOUT if the lock cannot
......
......@@ -65,32 +65,41 @@ extern tao_remote_camera* tao_remote_camera_create(
unsigned flags);
/**
* Attach an existing remote camera to the address space of the caller.
* @brief Attach an existing remote camera to the address space of the caller.
*
* This function attaches an existing remote camera to the address space of the
* caller. As a result, the number of attachments of the remote camera is
* caller. As a result, the number of attachments on the returned camera is
* incremented by one. When the camera is no longer used by the caller, the
* caller must call tao_remote_camera_detach() to detach the camera from its
* address space, decrement its number of attachments by one and eventually
* free the shared memory associated with the camera.
* caller is responsible of calling tao_remote_camera_detach() to detach the
* camera from its address space, decrement its number of attachments by one
* and eventually free the shared memory associated with the camera.
*
* @warning The same process must not attach a remote camera more than once.
* In principle, the same process may attach a remote camera more than once but
* each attachment, due to tao_remote_camera_attach() or to
* tao_remote_camera_create(), should be matched by a
* tao_remote_camera_detach() with the corresponding address in the caller's
* address space.
*
* @param shmid Unique identifier of the shared object.
* @param shmid Shared memory identifier.
*
* @return The address of the remote camera in the address space of the caller;
* `NULL` on failure.
* `NULL` in case of failure. Even tough the arguments are correct, an
* error may arise if the camera has been destroyed before attachment
* completes.
*
* @see tao_remote_camera_detach, tao_remote_camera_get_shmid.
* @see tao_remote_camera_detach().
*/
extern tao_remote_camera* tao_remote_camera_attach(
tao_shmid shmid);
/**
* Detach a remote camera.
* @brief Detach a remote camera from the address space of the caller.
*
* Detach a remote camera from the address space of the caller and decrement
* the number of attachments of the remote camera.
* This function detaches a remote camera from the address space of the caller
* and decrements the number of attachments of the remote camera. If the
* number of attachements reaches zero, the shared memory segment backing the
* storage of the camera is destroyed (unless bit @ref TAO_PERSISTENT was set
* at camera creation).
*
* @warning Detaching a remote camera does not detach shared arrays backing the
* storage of the images acquired by this camera. They have to be explicitly
......@@ -99,62 +108,107 @@ extern tao_remote_camera* tao_remote_camera_attach(
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*
* @see tao_remote_camera_attach.
* @see tao_remote_camera_attach().
*/
extern tao_status tao_remote_camera_detach(
tao_remote_camera* cam);
/**
* Get the identifier of remote camera data.
* @brief Get the size of a remote camera.
*
* This function yields the number of bytes of shared memory occupied by the
* remote camera. The size is constant for the life of the camera, it is thus
* not necessary to have locked the camera to retrieve its identifier.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller and locked by the caller.
* the caller.
*
* @return The identifier of the remote camera data. This value can be used by
* another process to attach to its address space the remote camera.
* `TAO_BAD_SHMID` is returned if @a cam is `NULL`. Whatever the
* result, the last caller's error is left unchanged.
* @return The number of bytes of the shared memory segment backing the storage
* of the remote camera, `0` if @a cam is `NULL`. Whatever the result,
* this getter function leaves the caller's last error unchanged.
*/
extern size_t tao_remote_camera_get_size(
const tao_remote_camera* cam);
/**
* @brief Get the type identifier of a remote camera.
*
* @see tao_remote_camera_attach.
* This function yields the identifier of the type of the remote camera. The
* type identifier is constant for the life of the camera, it is thus not
* necessary to have locked the camera to retrieve its identifier.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return The type identifier of the remote camera, `0` if @a cam is `NULL`.
* Whatever the result, this getter function leaves the caller's last
* error unchanged.
*/
extern tao_shmid tao_remote_camera_get_shmid(
extern uint32_t tao_remote_camera_get_type(
const tao_remote_camera* cam);
/**
* Get the name of the owner/creator of a remote camera.
* @brief Get the shared memory identifier of a remote camera.
*
* This function yields the shared memory identifier of the remote camera.
* This value can be used by another process to attach to its address space the
* remote camera. The shared memory identifier is constant for the life of the
* camera, it is thus not necessary to have locked the camera to retrieve its
* identifier.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return The name of the remote camera owner. An empty string if `cam` is
* `NULL`. Whatever the result, the last caller's error is left
* unchanged.
* @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.
*
* @see tao_remote_camera_attach.
*/
extern const char* tao_remote_camera_get_owner(
extern tao_shmid tao_remote_camera_get_shmid(
const tao_remote_camera* cam);
/**
* Lock a remote camera for exclusive access.
*
* Lock a remote camera for exclusive access. The caller is responsible for
* eventually releasing the lock with tao_remote_camera_unlock().
* This function locks a remote camera for exclusive (read and write) access.
* The camera must be attached to the address space of the caller. In case of
* success, the caller is responsible for calling tao_unlock_shared_camera()
* to eventually release the lock.
*
* @warning The same thread/process must not attempt to lock the same camera
* more than once and should unlock it as soon as possible.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*/
extern tao_status tao_remote_camera_lock(
tao_remote_camera* cam);
/**
* Unlock a remote camera.
*
* This function unlocks a remote camera that has been successfully locked by
* the caller.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*/
extern tao_status tao_remote_camera_unlock(
tao_remote_camera* cam);
/**
* Attempt to immediately lock a remote camera for exclusive access.
*
* Try to lock a remote camera for exclusive access without blocking. The
* caller is responsible for eventually releasing the lock with
* tao_remote_camera_unlock().
* This function attempts to lock a remote camera for exclusive (read and
* write) access without blocking. The caller is responsible for eventually
* releasing the lock with tao_remote_camera_unlock().
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
......@@ -169,9 +223,10 @@ extern tao_status tao_remote_camera_try_lock(
* Attempt to lock a remote camera for exclusive access with an absolute time
* limit.
*
* Try to lock a remote camera for exclusive access without
* blocking more than a given duration. The caller is responsible for
* eventually releasing the lock with tao_remote_camera_unlock().
* This function attempts to lock a remote camera for exclusive (read and
* write) access without blocking beyond a given time limit. The caller is
* responsible for eventually releasing the lock with
* tao_remote_camera_unlock().
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
......@@ -190,9 +245,10 @@ extern tao_status tao_remote_camera_abstimed_lock(
* Attempt to lock a remote camera for exclusive access with a relative time
* limit.
*
* Try to lock a remote camera for exclusive access without
* blocking more than a given duration. The caller is responsible for
* eventually releasing the lock with tao_remote_camera_unlock().
* This function attempts to lock a remote camera for exclusive (read and
* write) access without blocking more than a given duration. The caller is
* responsible for eventually releasing the lock with
* tao_remote_camera_unlock().
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
......@@ -212,30 +268,204 @@ extern tao_status tao_remote_camera_timed_lock(
double secs);
/**
* Unlock a remote camera.
* Signal a condition variable to at most one thread waiting on a remote camera.
*
* This function restarts one of the threads that are waiting on the condition
* variable of the camera. Nothing happens, if no threads are waiting on the
* condition variable.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
* @return @ref TAO_OK if successful; @ref TAO_ERROR in case of failure.
*
* @see tao_shared_object_unlock.
* @see tao_remote_camera_broadcast_condition(),
* tao_remote_camera_wait_condition().
*/
extern tao_status tao_remote_camera_unlock(
extern tao_status tao_remote_camera_signal_condition(
tao_remote_camera* cam);
/**
* Get the current state of the camera.
* Signal a condition to all threads waiting on a remote camera.
*
* @param cam Address of remote camera in address space of caller.
* This function behaves like tao_remote_camera_signal_condition() except that
* all threads waiting on the condition variable of the camera are restarted.
* Nothing happens, if no threads are waiting on the condition variable.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK if successful; @ref TAO_ERROR in case of failure.
*
* @see tao_remote_camera_signal_condition(),
* tao_remote_camera_wait_condition().
*/
extern tao_status tao_remote_camera_broadcast_condition(
tao_remote_camera* cam);
/**
* Wait for a condition to be signaled for a remote camera.
*
* This function atomically unlocks the exclusive lock associated with the
* remote camera and waits for its associated condition variable to be
* signaled. The thread execution is suspended and does not consume any CPU
* time until the condition variable is signaled. The mutex of the camera must
* have been locked (e.g., with tao_remote_camera_lock()) by the calling thread
* on entrance to this function. Before returning to the calling thread, this
* function re-acquires the mutex.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return @ref TAO_OK on success, @ref TAO_ERROR in case of failure.
*
* @see tao_remote_camera_lock(),
* tao_remote_camera_signal_condition().
*/
extern tao_status tao_remote_camera_wait_condition(
tao_remote_camera* cam);
/**
* Wait for a condition to be signaled for a remote camera without blocking
* longer than an absolute time limit.
*
* This function behaves like tao_remote_camera_wait_condition() but blocks no
* longer than a given duration.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @param lim Absolute time limit with the same conventions as
* tao_get_current_time().
*
* @return @ref TAO_OK if the lock has been locked by the caller before the
* specified number of seconds, @ref TAO_TIMEOUT if timeout occured
* before or @ref TAO_ERROR in case of error.
*/
extern tao_status tao_remote_camera_abstimed_wait_condition(
tao_remote_camera* cam,
const tao_time* lim);
/**
* Wait for a condition to be signaled for a remote camera without blocking
* longer than a relative time limit.
*
* This function behaves like tao_remote_camera_wait_condition() but blocks no
* longer than a given duration.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @param secs Maximum amount of time (in seconds). If this amount of time
* is very large, e.g. more than @ref TAO_MAX_TIME_SECONDS, the
* effect is the same as calling
* tao_remote_camera_wait_condition().
*
* @return @ref TAO_OK if the lock has been locked by the caller before the
* specified number of seconds, @ref TAO_TIMEOUT if timeout occured
* before or @ref TAO_ERROR in case of error.
*/
extern tao_status tao_remote_camera_timed_wait_condition(
tao_remote_camera* cam,
double secs);
/**
* Get the name of the owner of a remote camera.
*
* This function yields the name of the owner of the remote camera. This
* information is immutable and the camera needs not be locked by the caller.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return The name of the remote camera owner or an empty string `""` for a
* `NULL` camera pointer. Whatever the result, this getter function
* leaves the caller's last error unchanged.
*/
extern const char* tao_remote_camera_get_owner(
const tao_remote_camera* cam);
/**
* Get the number of output images of a remote camera.
* This function yields the length of the cyclic list of shared arrays
* memorized by the owner of a remote camera. This information is immutable
* and the camera needs not be locked by the caller.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller and locked by the caller.
*
* @return The length of the list of shared arrays memorized by the owner of
* the remote camera, `0` if @a cam is `NULL`. Whatever the result,
* this getter function leaves the caller's last error unchanged.
*
* @see tao_remote_camera_lock.
*/
extern long tao_remote_camera_get_nbufs(
const tao_remote_camera* cam);
/**
* Get the serial number of the last available output image of a remote camera.
*
* This function yields the serial number of the last image available from a
* remote camera. This is also the number of images posted so far by the
* server owning the remote camera.
*
* @return `-1` if @a cam is `NULL`; otherwise, `0` if device not yet open, `1`
* if device open but no acquisition is running, `2` if acquisition is
* running.
* The serial number of last image may change (i.e., when acquisition is
* running), but serial number is stored in an *atomic* variable, so the caller
* needs not lock the remote camera.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller and locked by the caller.
*
* @return A nonnegative integer. A strictly positive value which is the
* serial number of the last available image if any, `0` if image
* acquisition has not yet started of if `cam` is `NULL`. Whatever the
* result, this getter function leaves the caller's last error
* unchanged.
*
* @see tao_remote_camera_lock.
*/
extern tao_serial tao_remote_camera_get_serial(
const tao_remote_camera* cam);
/**
* Get the current state of the server owning a remote camera.
*
* This function yields the current state of the server owning the remote
* camera.
*
* The server state is stored in an *atomic* variable, so the caller needs not
* lock the remote camera.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return The state of the remote server, @ref TAO_STATE_KILLED if `cam` is
* `NULL`. Whatever the result, this getter function leaves the
* caller's last error unchanged.
*/
extern tao_state tao_remote_camera_get_state(
const tao_remote_camera* cam);
/**
* Check whether the server owning a remote camera is alive.
*
* This function uses the current state of the server owning the remote camera
* to determine whether the server is alive.
*
* The server state is stored in an *atomic* variable, so the caller needs not
* lock the remote camera.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller.
*
* @return A boolean result; `false` if `cam` is `NULL`. Whatever the result,
* this getter function leaves the caller's last error unchanged.
*/
extern int tao_remote_camera_is_alive(
const tao_remote_camera* cam);
/**
* Get the pixel type for the captured images after pre-processing.
*
......@@ -392,50 +622,6 @@ extern double tao_remote_camera_get_framerate(
extern double tao_remote_camera_get_exposuretime(
const tao_remote_camera* cam);
/**
* Get the length of the cyclic list of shared arrays memorized by the owner of
* a remote camera.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller and locked by the caller.
*
* @note The length of the list is immutable, the caller does not have to lock
* the remote camera to insure consistency of the result.
*
* @return The length of the list of shared arrays memorized by the owner of
* the remote camera, `0` if @a cam is `NULL`. Whatever the result,
* the last caller's error is left unchanged.
*
* @see tao_remote_camera_lock.
*/
extern long tao_remote_camera_get_nbufs(
const tao_remote_camera* cam);
/**
* Get the serial number of the last available image.
*
* This function yields the serial number of the last image available from a
* remote camera. This is also the number of images posted by the server
* owning the remote camera so far.
*
* @param cam Pointer to a remote camera attached to the address space of
* the caller and locked by the caller.
*
* @note The serial number of last image may change (i.e., when acquisition is
* running), but the caller may not have locked the remote camera because
* the serial number is an atomic variable. For efficiency reasons, this
* function does not perform error checking.
*
* @return A nonnegative integer. A strictly positive value which is the
* serial number of the last available image if any, 0 if image
* acquisition has not yet started of if `cam` is `NULL`. Whatever the
* result, the last caller's error is left unchanged.
*
* @see tao_remote_camera_lock.
*/
extern tao_serial tao_remote_camera_get_serial(
const tao_remote_camera* cam);
/**
* Start acquisition by a remote camera with optional configuration.
*
......
This diff is collapsed.
This diff is collapsed.
......@@ -158,12 +158,12 @@ extern tao_shared_object* tao_shared_object_create(
* This function attaches an existing shared 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 reponsible of calling tao_shared_object_detach() to detach the
* caller is responsible of calling tao_shared_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.
*
* The same process may attach a shared object more than once but each
* attachment, due to tao_shared_object_attach() or to
* In principle, the same process may attach a shared object more than once but
* each attachment, due to tao_shared_object_attach() or to
* tao_shared_object_create(), should be matched by a
* tao_shared_object_detach() with the corresponding address in the caller's
* address space.
......@@ -174,6 +174,8 @@ extern tao_shared_object* tao_shared_object_create(
* `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_shared_object_detach().
*/
extern tao_shared_object* tao_shared_object_attach(
tao_shmid shmid);
......@@ -191,6 +193,8 @@ extern tao_shared_object* tao_shared_object_attach(
* the caller.
*
* @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
*
* @see tao_shared_object_attach().
*/
extern tao_status tao_shared_object_detach(
tao_shared_object* obj);
......@@ -198,13 +202,16 @@ extern tao_status tao_shared_object_detach(
/**
* @brief Get the size of a shared object.
*
* This function yields the number of bytes of shared memory occupied by the
* shared 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 shared object attached to the address space of
* the caller.
*
* @return The number of bytes of the shared memory segment backing the storage
* of the shared object. This function never pushes an error on the
* caller's last error, a zero size is returned for a `NULL` object
* pointer.
* of the shared object, `0` if @a obj is `NULL`. Whatever the result,
* this getter function leaves the caller's last error unchanged.
*/
extern size_t tao_shared_object_get_size(
const tao_shared_object* obj);
......@@ -212,30 +219,37 @@ extern size_t tao_shared_object_get_size(
/**
* @brief Get the type identifier of a shared object.
*
* This function yields the identifier of the type of the shared 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 shared object attached to the address space of
* the caller.
*
* @return The type identifier of the shared object. This function never
* pushes an error on the caller's last error, a zero type is returned
* for a `NULL` object pointer.
* @return The type identifier of the shared object, `0` if @a obj is `NULL`.
* Whatever the result, this getter function leaves the caller's last
* error unchanged.
*/
extern uint32_t tao_shared_object_get_type(
const tao_shared_object* obj);