source: rtems/cpukit/score/include/rtems/score/corerwlockimpl.h @ 8e7db68c

4.115
Last change on this file since 8e7db68c was c499856, checked in by Chris Johns <chrisj@…>, on 03/20/14 at 21:10:47

Change all references of rtems.com to rtems.org.

  • Property mode set to 100644
File size: 5.8 KB
Line 
1/**
2 * @file
3 *
4 * @brief Inlined Routines Associated with the SuperCore RWLock
5 *
6 * This include file contains all of the inlined routines associated
7 * with the SuperCore RWLock.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2008.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.org/license/LICENSE.
17 */
18
19#ifndef _RTEMS_SCORE_CORERWLOCKIMPL_H
20#define _RTEMS_SCORE_CORERWLOCKIMPL_H
21
22#include <rtems/score/corerwlock.h>
23#include <rtems/score/thread.h>
24#include <rtems/score/watchdog.h>
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/**
31 * @addtogroup ScoreRWLock
32 */
33/**@{**/
34
35/**
36 *  The following type defines the callout which the API provides
37 *  to support global/multiprocessor operations on RWLocks.
38 */
39typedef void ( *CORE_RWLock_API_mp_support_callout )(
40                 Thread_Control *,
41                 Objects_Id
42             );
43
44/**
45 *  Core RWLock handler return statuses.
46 */
47typedef enum {
48  /** This status indicates that the operation completed successfully. */
49  CORE_RWLOCK_SUCCESSFUL,
50  /** This status indicates that the thread was blocked waiting for an */
51  CORE_RWLOCK_WAS_DELETED,
52  /** This status indicates that the rwlock was not immediately available. */
53  CORE_RWLOCK_UNAVAILABLE,
54  /** This status indicates that the calling task was willing to block
55   *  but the operation was unable to complete within the time allotted
56   *  because the resource never became available.
57   */
58  CORE_RWLOCK_TIMEOUT
59}   CORE_RWLock_Status;
60
61/** This is the last status value.
62 */
63#define CORE_RWLOCK_STATUS_LAST CORE_RWLOCK_TIMEOUT
64
65/**
66 *  This is used to denote that a thread is blocking waiting for
67 *  read-only access to the RWLock.
68 */
69#define CORE_RWLOCK_THREAD_WAITING_FOR_READ  0
70
71/**
72 *  This is used to denote that a thread is blocking waiting for
73 *  write-exclusive access to the RWLock.
74 */
75#define CORE_RWLOCK_THREAD_WAITING_FOR_WRITE 1
76
77/**
78 *  @brief Initialize a RWlock.
79 *
80 *  This routine initializes the RWLock based on the parameters passed.
81 *
82 *  @param[in] the_rwlock is the RWLock to initialize
83 *  @param[in] the_rwlock_attributes define the behavior of this instance
84 */
85void _CORE_RWLock_Initialize(
86  CORE_RWLock_Control       *the_rwlock,
87  CORE_RWLock_Attributes    *the_rwlock_attributes
88);
89
90/**
91 *  @brief Obtain RWLock for reading.
92 *
93 *  This routine attempts to obtain the RWLock for read access.
94 *
95 *  @param[in] the_rwlock is the RWLock to wait for
96 *  @param[in] id is the id of the object being waited upon
97 *  @param[in] wait is true if the calling thread is willing to wait
98 *  @param[in] timeout is the number of ticks the calling thread is willing
99 *         to wait if @a wait is true.
100 *  @param[in] api_rwlock_mp_support is the routine to invoke if the
101 *         thread unblocked is remote
102 *
103 * @note Status is returned via the thread control block.
104 */
105
106void _CORE_RWLock_Obtain_for_reading(
107  CORE_RWLock_Control                 *the_rwlock,
108  Thread_Control                      *executing,
109  Objects_Id                           id,
110  bool                                 wait,
111  Watchdog_Interval                    timeout,
112  CORE_RWLock_API_mp_support_callout   api_rwlock_mp_support
113);
114
115/**
116 *  @brief Obtain RWLock for writing.
117 *
118 *  This routine attempts to obtain the RWLock for write exclusive access.
119 *
120 *  @param[in] the_rwlock is the RWLock to wait for
121 *  @param[in] id is the id of the object being waited upon
122 *  @param[in] wait is true if the calling thread is willing to wait
123 *  @param[in] timeout is the number of ticks the calling thread is willing
124 *         to wait if @a wait is true.
125 *  @param[in] api_rwlock_mp_support is the routine to invoke if the
126 *         thread unblocked is remote
127 *
128 * @note Status is returned via the thread control block.
129 */
130void _CORE_RWLock_Obtain_for_writing(
131  CORE_RWLock_Control                 *the_rwlock,
132  Thread_Control                      *executing,
133  Objects_Id                           id,
134  bool                                 wait,
135  Watchdog_Interval                    timeout,
136  CORE_RWLock_API_mp_support_callout   api_rwlock_mp_support
137);
138
139/**
140 *  @brief Release the RWLock.
141 *
142 *  This routine manually releases @a the_rwlock.  All of the threads waiting
143 *  for the RWLock will be readied.
144 *
145 *  @param[in] the_rwlock is the RWLock to surrender
146 *
147 *  @retval Status is returned to indicate successful or failure.
148 */
149CORE_RWLock_Status _CORE_RWLock_Release(
150  CORE_RWLock_Control *the_rwlock,
151  Thread_Control      *executing
152);
153
154/**
155 *  This routine assists in the deletion of a RWLock by flushing the
156 *  associated wait queue.
157 *
158 *  @param[in] _the_rwlock is the RWLock to flush
159 *  @param[in] _remote_extract_callout is the routine to invoke if the
160 *         thread unblocked is remote
161 *  @param[in] _status is the status to be returned to the unblocked thread
162 */
163#define _CORE_RWLock_Flush( _the_rwlock, _remote_extract_callout, _status) \
164  _Thread_queue_Flush( \
165    &((_the_rwlock)->Wait_queue), \
166    (_remote_extract_callout), \
167    (_status) \
168  )
169
170/**
171 *  @brief RWLock specific thread queue timeout.
172 *
173 *  This routine processes a thread which timeouts while waiting on
174 *  an RWLock's thread queue. It is called by the watchdog handler.
175 *
176 *  @param[in] id is the Id of thread to timeout
177 *  @param[in] ignored is an unused pointer to a caller defined area
178 */
179
180void _CORE_RWLock_Timeout(
181  Objects_Id  id,
182  void       *ignored
183);
184
185/**
186 * This method is used to initialize core rwlock attributes.
187 *
188 * @param[in] the_attributes pointer to the attributes to initialize.
189 */
190RTEMS_INLINE_ROUTINE void _CORE_RWLock_Initialize_attributes(
191  CORE_RWLock_Attributes *the_attributes
192)
193{
194  the_attributes->XXX = 0;
195}
196
197/** @} */
198
199#ifdef __cplusplus
200}
201#endif
202
203#endif
204/* end of include file */
Note: See TracBrowser for help on using the repository browser.