1 /* vim: set expandtab ts=4 sw=4: */
2 /*
3  * You may redistribute this program and/or modify it under the terms of
4  * the GNU General Public License as published by the Free Software Foundation,
5  * either version 3 of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
14  */
15 #ifndef SearchStore_H
16 #define SearchStore_H
17 
18 #ifdef SUBNODE
19     #error "this file should not be included in subnode"
20 #endif
21 
22 #include "dht/Address.h"
23 #include "memory/Allocator.h"
24 #include "benc/Object.h"
25 #include "util/log/Log.h"
26 #include "util/Linker.h"
27 Linker_require("dht/dhtcore/SearchStore.c")
28 
29 #include <stdint.h>
30 
31 
32 /**
33  * The number of nodes which will be held in a buffer when performing a search.
34  * It is important that this number is large enough because when a search yields results, the
35  * nodes which helped in get to those results have their reach number recalculated and if
36  * they are prematurely evicted, they will not have their number recalculated.
37  */
38 #define SearchStore_SEARCH_NODES 256
39 
40 /*--------------------Structures--------------------*/
41 
42 struct SearchStore
43 {
44     /** The means of getting memory to store each search. */
45     struct Allocator* const allocator;
46 
47     struct Log* const logger;
48 };
49 
50 /** Represents a single search */
51 struct SearchStore_Search
52 {
53     struct SearchStore* const store;
54     struct Allocator* const alloc;
55     void* callbackContext;
56 };
57 
58 struct SearchStore_Node;
59 struct SearchStore_Node
60 {
61     /** Number of milliseconds since the epoch when the search request was sent to this node. */
62     uint64_t timeOfRequest;
63 
64     /** The search. */
65     struct SearchStore_Search* search;
66 
67     /** The address of this node. */
68     struct Address address;
69 };
70 
71 
72 /*--------------------Prototypes--------------------*/
73 
74 /**
75  * Create a new SearchStore.
76  *
77  * @param allocator the means of aquiring memory for the new store.
78  * @param logger
79  */
80 struct SearchStore* SearchStore_new(struct Allocator* allocator, struct Log* logger);
81 
82 /**
83  * Create a new search.
84  *
85  * @param searchTarget the ID of the thing which we are searching for.
86  * @param store the SearchStore to allocate the search in.
87  * @param alloc the allocator to use for allocating this search.
88  * @return the new search or NULL if MAX_SEARCHES are already running.
89  */
90 struct SearchStore_Search* SearchStore_newSearch(uint8_t searchTarget[16],
91                                                  struct SearchStore* store,
92                                                  struct Allocator* alloc);
93 
94 /**
95  * Add a node to a search.
96  *
97  * @param address the address of the node to add.
98  * @param search the search to add the node to.
99  * @return -1 if this node has already been asked as part of this search, 0 otherwise.
100  */
101 int SearchStore_addNodeToSearch(struct Address* addr, struct SearchStore_Search* search);
102 
103 /**
104  * Get the next node to ask in this search.
105  * This will get the last node to be added to the search which has not been sent a request yet.
106  *
107  * @param search the search to get the node for.
108  * @param allocator the allocator to use for allocating the memory to store the output.
109  * @return the node which is copied from the storage to the allocated space.
110  */
111 struct SearchStore_Node* SearchStore_getNextNode(struct SearchStore_Search* search);
112 
113 #endif
114