1/**
2 * \file
3 * \brief octopus Query Interface Header file
4 *
5 * The server must implement this interface in order for dist2
6 * to work accordingly.
7 */
8
9/*
10 * Copyright (c) 2011, ETH Zurich.
11 * All rights reserved.
12 *
13 * This file is distributed under the terms in the attached LICENSE file.
14 * If you do not find this file, copies can be found by writing to:
15 * ETH Zurich D-INFK, Universitaetstrasse 6, CH-8092 Zurich. Attn: Systems Group.
16 */
17
18#ifndef OCTOPUS_QUERY_H_
19#define OCTOPUS_QUERY_H_
20
21#include <barrelfish/barrelfish.h>
22
23
24#include <octopus_server/service.h>
25#include <octopus/parser/ast.h>
26
27/**
28 * \brief Stores a binding for the given id.
29 *
30 * Used to find the event binding for a given RPC connection
31 * since in a regular flounder interface RPC calls are on on a
32 * different waitset we currently need two binding.
33 *
34 * \param type Binding type (RPC or Event)
35 * \param id Identifier unique per client
36 * \param binding Pointer value of binding
37 *
38 * \retval SYS_ERR_OK
39 * \retval OCT_ERR_UNSUPPORTED_BINDING
40 * \retval OCT_ERR_ENGINE_FAIL
41 * \retval LIB_ERR_MALLOC_FAIL
42 */
43errval_t set_binding(octopus_binding_type_t type, uint64_t id, void* binding);
44
45/**
46 * Given a query returns a number of record names matching
47 * the query. The record names are stored as a comma separated string
48 * in oct_query_state.
49 *
50 * \param ast Abstract Syntax Tree of query.
51 * \param dqs Contains the result of the query invocation.
52 *
53 * \retval SYS_ERR_OK
54 * \retval OCT_ERR_NO_RECORD
55 * \retval OCT_ERR_ENGINE_FAIL
56 */
57errval_t get_record_names(struct ast_object* ast, struct oct_query_state* dqs);
58
59/**
60 * \brief Returns a record matching the given query.
61 *
62 * \param ast Query supplied by client converted to AST.
63 * \param dqs Contains the result of the query invocation.
64 *
65 * \retval SYS_ERR_OK
66 * \retval OCT_ERR_NO_RECORD
67 * \retval OCT_ERR_ENGINE_FAIL
68 */
69errval_t get_record(struct ast_object* ast, struct oct_query_state* dqs);
70
71/**
72 * \brief Stores a record in the database.
73 *
74 * \param ast Record to set.
75 * \param mode A combination of modes as defined in getset.h.
76 * \param dqs Returned result of query invocation.
77 *
78 * \retval SYS_ERR_OK
79 * \retval OCT_ERR_ENGINE_FAIL
80 */
81errval_t set_record(struct ast_object* ast, uint64_t mode,
82        struct oct_query_state* dqs);
83
84/**
85 * \brief Deletes a record in the database.
86 *
87 * \param ast Record to delete.
88 * \param dqs Returned result of query invocation.
89 *
90 * \retval SYS_ERR_OK
91 * \retval OCT_ERR_NO_RECORD
92 * \retval OCT_ERR_ENGINE_FAIL
93 */
94errval_t del_record(struct ast_object*, struct oct_query_state*);
95
96/**
97 * Sets a watch for a record(s) matching the given query. The Query Engine
98 * is supposed to use the drs struct to reply to the client once the watch is
99 * triggered.
100 *
101 * \param b RPC Binding
102 * \param ast AST to watch for
103 * \param mode When to trigger the watch (del or set).
104 * \param drs Reply state used to reply to the client.
105 * \param wid ID of the installed watch (used for remove).
106 *
107 * \retval SYS_ERR_OK
108 * \retval OCT_ERR_ENGINE_FAIL
109 */
110errval_t set_watch(struct octopus_binding* b, struct ast_object* ast,
111        uint64_t mode, struct oct_reply_state* drs, uint64_t* wid);
112
113/**
114 * \brief Removes a watch
115 *
116 * \param b Binding of caller
117 * \param id Trigger Id supplied by caller
118 * \param dqs Query state
119 *
120 * \retval SYS_ERR_OK
121 * \retval OCT_ERR_INVALID_ID
122 * \retval OCT_ERR_ENGINE_FAIL
123 */
124errval_t del_watch(struct octopus_binding* b, octopus_trigger_id_t id,
125        struct oct_query_state* dqs);
126
127/**
128 * \brief Adds a subscription.
129 *
130 * \param b RPC binding of subscriber.
131 * \param ast Subscription template (to match with published records).
132 * \param trigger_fn Client handler function.
133 * \param state Additional state argument supplied by client.
134 * \param drs Returned result of query invocation.
135 *
136 * \retval SYS_ERR_OK
137 * \retval OCT_ERR_MAX_SUBSCRIPTIONS
138 * \retval OCT_ERR_ENGINE_FAIL
139 * \retval LIB_ERR_MALLOC_FAIL
140 */
141errval_t add_subscription(struct octopus_binding* b, struct ast_object* ast,
142        uint64_t trigger_fn, uint64_t state, struct oct_reply_state* drs);
143
144/**
145 * \brief Deletes a subscription for a given (Binding, Id) pair.
146 *
147 * \param b RPC binding of subscriber.
148 * \param id ID of the subscription.
149 * \param dqs Returned result of query invocation.
150 *
151 * \retval SYS_ERR_OK
152 * \retval OCT_ERR_NO_SUBSCRIPTION
153 * \retval OCT_ERR_ENGINE_FAIL
154 */
155errval_t del_subscription(struct octopus_binding* b, uint64_t id,
156        struct oct_query_state* dqs);
157
158/**
159 * Find all subscribers with a matching subscription for the given
160 * AST.
161 *
162 * \param ast Record to match with stored subscription.
163 * \param dqs Returned result of query invocation.
164 *
165 * \retval SYS_ERR_OK
166 * \retval OCT_ERR_NO_SUBSCRIBERS
167 * \retval OCT_ERR_ENGINE_FAIL
168 */
169errval_t find_subscribers(struct ast_object* ast, struct oct_query_state* dqs);
170
171/**
172 * \brief Find the event binding of the client based on his RPC binding.
173 *
174 * \param binding RPC binding
175 * \return Pointer of event binding or NULL on error.
176 */
177struct octopus_binding* get_event_binding(struct octopus_binding* binding);
178
179#endif /* OCTOPUS_QUERY_H_ */
180