1 | /* Copyright 2016 Google Inc. |
2 | |
3 | Licensed under the Apache License, Version 2.0 (the "License"); |
4 | you may not use this file except in compliance with the License. |
5 | You may obtain a copy of the License at |
6 | |
7 | http://www.apache.org/licenses/LICENSE-2.0 |
8 | |
9 | Unless required by applicable law or agreed to in writing, software |
10 | distributed under the License is distributed on an "AS IS" BASIS, |
11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
12 | See the License for the specific language governing permissions and |
13 | limitations under the License. */ |
14 | |
15 | #ifndef NSYNC_PUBLIC_NSYNC_NOTE_H_ |
16 | #define NSYNC_PUBLIC_NSYNC_NOTE_H_ |
17 | |
18 | #include "nsync_cpp.h" |
19 | #include "nsync_time.h" |
20 | |
21 | NSYNC_CPP_START_ |
22 | |
23 | /* An nsync_note represents a single bit that can transition from 0 to 1 at |
24 | most once. When 1, the note is said to be notified. There are operations |
25 | to wait for the transition, which can be triggered either by an explicit |
26 | call, or timer expiry. Notes can have parent notes; a note becomes notified |
27 | if its parent becomes notified. */ |
28 | typedef struct nsync_note_s_ *nsync_note; |
29 | |
30 | /* Return a freshly allocated nsync_note, or NULL if an nsync_note cannot be |
31 | created. |
32 | |
33 | If parent!=NULL, the allocated nsync_note's parent will be parent. The |
34 | newaly allocated note will be automatically notified at abs_deadline, and is |
35 | notified at initialization if abs_deadline==nsync_zero_time. |
36 | |
37 | nsync_notes should be passed to nsync_note_free() when no longer needed. */ |
38 | nsync_note nsync_note_new (nsync_note parent, nsync_time abs_deadline); |
39 | |
40 | /* Free resources associated with n. Requires that n was allocated by |
41 | nsync_note_new(), and no concurrent or future operations are applied to n |
42 | directly. |
43 | It is legal to call nsync_note_free() on a node even if it has a parent or |
44 | children that are in use; if n has both a parent and children, n's |
45 | parent adopts its children. */ |
46 | void nsync_note_free (nsync_note n); |
47 | |
48 | /* Notify n and all its descendants. */ |
49 | void nsync_note_notify (nsync_note n); |
50 | |
51 | /* Return whether n has been notified. */ |
52 | int nsync_note_is_notified (nsync_note n); |
53 | |
54 | /* Wait until n has been notified or abs_deadline is reached, and return |
55 | whether n has been notified. If abs_deadline==nsync_time_no_deadline, |
56 | the deadline is far in the future. */ |
57 | int nsync_note_wait (nsync_note n, nsync_time abs_deadline); |
58 | |
59 | /* Return the expiry time associated with n. |
60 | This is the minimum of the abs_deadline passed on creation and that of any |
61 | of its ancestors. */ |
62 | nsync_time nsync_note_expiry (nsync_note n); |
63 | |
64 | NSYNC_NOTE_CPP_OVERLOAD_ |
65 | NSYNC_CPP_END_ |
66 | |
67 | #endif /*NSYNC_PUBLIC_NSYNC_NOTE_H_*/ |
68 | |