1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
/*
* Copyright (c) 2017-2019 Cisco and/or its affiliates.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef contentStoreEntry_h
#define contentStoreEntry_h
#include <src/content_store/listLRU.h>
#include <src/core/message.h>
struct contentstore_entry;
typedef struct contentstore_entry ContentStoreEntry;
/**
* The max time allowed for an ExpiryTime. Will never be exceeded.
*/
extern const uint64_t contentStoreEntry_MaxExpiryTime;
/**
* Creates a new `ContentStoreEntry` instance, acquiring a reference to the
* supplied `Message`.
*
* @param message the message to store
* @param listLRU the LRU list that this entry will be stored in.
* @return A newly created `ContentStoreEntry` instance that must eventually be
* released by calling
* {@link contentStoreEntry_Release}.
*
* @see contentStoreEntry_Release
*/
ContentStoreEntry *contentStoreEntry_Create(Message *objectMessage,
ListLru *listLRU);
/**
* Returns a reference counted copy of the supplied `ContentStoreEntry`.
*
* @param original the ContentStoreEntry to return a reference to.
* @return Reference counted copy, must call
* <code>contentStoreEntry_Destroy()</code> on it.
*/
ContentStoreEntry *contentStoreEntry_Acquire(const ContentStoreEntry *original);
/**
* Releases one reference count and destroys object when reaches zero
*
* @param [in,out] entryPtr A pointer to an allocated ContentStoreEntry
*
*/
void contentStoreEntry_Release(ContentStoreEntry **entryPtr);
/**
* Returns a pointer to the contained {@link Message}.
* The caller must called {@link message_Acquire()} if they want to keep a
* reference to the returned message.
*
* @param storeEntry the ContentStoreEntry from which to retrieve the `Message`
* pointer.
* @return the address of the `Message` contained in the storeEntry.
* @see message_Acquire
*/
Message *contentStoreEntry_GetMessage(const ContentStoreEntry *storeEntry);
/**
* Return true if the message stored in this `ContentStoreEntry` has an
* ExpiryTime.
*
* @param storeEntry the ContentStoreEntry containing the message.
* @return true if the referenced message has an ExpiryTime. False, otherwise.
*/
bool contentStoreEntry_HasExpiryTimeTicks(const ContentStoreEntry *storeEntry);
/**
* Return the ExpiryTime stored in this `ContentStoreEntry`.
*
* @param storeEntry the ContentStoreEntry from which to retrieve the `Message`
* pointer.
* @return the address of the `Message` contained in the storeEntry.
*/
uint64_t contentStoreEntry_GetExpiryTimeTicks(
const ContentStoreEntry *storeEntry);
/**
* A signum function comparing two `ContentStoreEntry` instances, using their
* ExpiryTime and, if necessary, the addresses of the referenced Message. In
* other words, if two ContentStoreEntries have the same ExpiryTime, the
* comparison will then be made on the memory addresses of the Messages
* referenced by the ContentStoreEntrys. So, the only way two ContentStoreEntrys
* will compare equally (0) is if they both have the same ExpiryTime and
* reference the same Message.
*
* Used to determine the ordering relationship of two `ContentStoreEntry`
* instances. This is used by the {@link ListTimeOrdered} to keep a list of
* ContentStoreEntrys, sorted by ExpiryTime.
*
* @param [in] storeEntry1 A pointer to a `ContentStoreEntry` instance.
* @param [in] storeEntry2 A pointer to a `ContentStoreEntry` instance to be
* compared to `storeEntry1`.
*
* @return 0 if `storeEntry1` and `storeEntry2` are equivalent
* @return < 0 if `storeEntry1` < `storeEntry2`
* @return > 0 if `storeEntry1` > `storeEntry2`
*
* Example:
* @code
* {
* ContentStoreEntry *entry1 = contentStoreEntry_Create(...);
* ContentStoreEntry *entry2 = contentStoreEntry_Create(...);
*
* int val = contentStoreEntry_CompareExpiryTime(entry1, entry2);
* if (val < 0) {
* // entry1 has a lower ExpiryTime, or the same ExpiryTime as entry2
* and a different message. } else if (val > 0) {
* // entry2 has a lower ExpiryTime, or the same ExpiryTime as entry1
* and a different message. } else {
* // entry1 and entry2 have the same ExpiryTime AND the same message.
* }
*
* contentStoreEntry_Release(&entry1);
* contentStoreEntry_Release(&entry2);
*
* }
* @endcode
*/
int contentStoreEntry_CompareExpiryTime(const ContentStoreEntry *storeEntry1,
const ContentStoreEntry *storeEntry2);
/**
* Move this entry to the head of the LRU list
*
* Moves the entry to the head of the LRU list it was created with
*
* @param [in] storeEntry An allocated ContenstoreEntry
*/
void contentStoreEntry_MoveToHead(ContentStoreEntry *storeEntry);
#endif // contentStoreEntry_h
|
