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
21NSYNC_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. */
28typedef 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. */
38nsync_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. */
46void nsync_note_free (nsync_note n);
47
48/* Notify n and all its descendants. */
49void nsync_note_notify (nsync_note n);
50
51/* Return whether n has been notified. */
52int 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. */
57int 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. */
62nsync_time nsync_note_expiry (nsync_note n);
63
64NSYNC_NOTE_CPP_OVERLOAD_
65NSYNC_CPP_END_
66
67#endif /*NSYNC_PUBLIC_NSYNC_NOTE_H_*/
68