rename dist2 interface to octopus
[barrelfish] / if / octopus.if
1 /*
2  * Copyright (c) 2007, 2008, 2009, ETH Zurich.
3  * All rights reserved.
4  *
5  * This file is distributed under the terms in the attached LICENSE file.
6  * If you do not find this file, copies can be found by writing to:
7  * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
8  */
9
10 interface dist2 "dist2 RPC Interface" {
11
12     alias mode uint64;
13     alias trigger_id uint64;
14     typedef enum {BINDING_RPC, BINDING_EVENT} binding_type;
15
16     // XXX: No flounder support for pointer values
17     typedef struct {
18         errval in_case;
19         binding_type send_to;
20         mode m;
21         uint64 trigger;
22         uint64 st;
23     } trigger;
24
25     //
26     // Binding Identification
27     //
28     rpc get_identifier(out uint64 id);
29     rpc identify(in uint64 id, in binding_type type);
30     
31     
32     //
33     // Get/Set API
34     //
35
36     /**
37      * \param query Records to find.
38      * \param t Additional trigger to watch for future events.
39      * \param output Comma separated string of record names or NULL on error.
40      * \param tid Id of registered trigger (0 in case no trigger registered).
41      * \param error_code Error value of request.
42      */
43     rpc get_names(in string query, in trigger t, out string output, out trigger_id tid, out errval error_code);
44     
45     /**
46      * \param query Record to find.
47      * \param t Additional trigger to watch for future events.
48      * \param output Retrieved record or NULL on error.
49      * \param tid Id of registered trigger (0 in case no trigger registered).
50      * \param error_code Error value of request.
51      */
52     rpc get(in string query, in trigger t, out string output, out trigger_id tid, out errval error_code);
53         
54     /**
55      * \param query Record to set.
56      * \param mode Set mode (see getset.h).
57      * \param t Additional trigger to watch for future events.
58      * \param get Return record if it has been set.
59      * \param record In case get is true and no error_code is ok 
60      * contains record, otherwise NULL
61      * \param tid Id of registered trigger (0 in case no trigger registered).
62      * \param error_code Error value of request
63      */
64     rpc set(in string query, in uint64 mode, in trigger t, in bool get, out string record, out trigger_id tid, out errval error_code);
65     
66     /**
67      * \param query Record(s) to delete.
68      * \param t Additional trigger to watch for future events.
69      * \param tid Id of registered trigger (0 in case no trigger registered).
70      * \param error_code Error value of request
71      */
72     rpc del(in string query, in trigger t, out trigger_id tid, out errval error_code);    
73     
74     /**
75      * \param query
76      * \param t Additional trigger to watch for future events.
77      * \param tid Id of registered trigger (0 in case no trigger registered).
78      * \param error_code Error value of request.
79      */
80     rpc exists(in string query, in trigger t, out trigger_id tid, out errval error_code);
81     
82     /**
83      * \brief Blocks until a record matching the provided query is registered.
84      *
85      * This was introduced specifically for the nameserver API
86      * due to limitations of the memory allocation during bootstrapping we
87      * can't use THC but need to support nameservice blocking lookup.
88      * If you use this call you might want to consider using
89      * a combination of get and triggers.
90      *
91      * \param query
92      * \param record
93      * \param error_code
94      */
95     rpc wait_for(in string query, out string record, out errval error_code);
96     
97     /**
98      * \brief Used to remove Triggers in case they are not needed anymore.
99      *
100      * Note that non persistent trigger are removed automatically after 
101      * they have fired. For persistent triggers be aware that you might
102      * still get a notification after the trigger has been removed because
103      * trigger events are sent over another binding.
104      *
105      * \param id Trigger ID to remove
106      * \param error_code Error of operation
107      */
108     rpc remove_trigger(in uint64 id, out errval error_code);
109     
110
111     //
112     // Publish/Subscribe API
113     //
114     
115     /**
116      * \param query
117      * \param client_state Additional state supplied by client.
118      * \param id Identifier for this subscription supplied by server.
119      * \param error_code Status of request.
120      */
121     rpc subscribe(in string query, in uint64 trigger_fn, in uint64 state, out uint64 id, out errval error_code);
122     
123     /**
124      * \param id Id for the subscription
125      * \param error_code Status of request
126      */
127     rpc unsubscribe(in uint64 id, out errval error_code);
128     
129     /**
130      * \param record Message to publish.
131      * \param error_code Status of request.
132      */
133     rpc publish(in string record, out errval error_code);
134
135
136     //
137     // Async events (sent by server to client)
138     //
139     message trigger(trigger_id id, uint64 trigger_fn, mode m, string record, uint64 state);
140     message subscription(trigger_id id, uint64 trigger_fn, mode m, string record, uint64 state);
141     
142
143     //
144     // Backward compability with chips
145     //
146     
147     // Simple capability storage
148     rpc get_cap(in string key, out cap retcap, out errval reterr);
149     rpc put_cap(in string key, in cap storecap, out errval reterr);
150     rpc remove_cap(in string key, out errval reterr);
151 };