Apache Mesos
scheduler.hpp
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 
17 #ifndef __MESOS_V1_SCHEDULER_HPP__
18 #define __MESOS_V1_SCHEDULER_HPP__
19 
20 #include <functional>
21 #include <memory>
22 #include <queue>
23 #include <string>
24 
25 #include <mesos/http.hpp>
26 
27 #include <mesos/v1/mesos.hpp>
28 
30 
31 #include <process/future.hpp>
32 
33 #include <stout/option.hpp>
34 
35 namespace mesos {
36 
37 namespace master {
38 namespace detector {
39 class MasterDetector;
40 } // namespace detector {
41 } // namespace master {
42 
43 namespace v1 {
44 namespace scheduler {
45 
46 class MesosProcess; // Forward declaration.
47 
48 // Abstract interface for connecting a scheduler to Mesos.
49 class MesosBase
50 {
51 public:
52  // Empty virtual destructor (necessary to instantiate subclasses).
53  virtual ~MesosBase() {}
54  virtual void send(const Call& call) = 0;
55  virtual process::Future<APIResult> call(const Call& callMessage) = 0;
56  virtual void reconnect() = 0;
57 };
58 
59 
60 // Concrete implementation that connects a scheduler to a Mesos master.
61 // Abstracts master detection (connection and disconnection).
62 //
63 // Expects three callbacks, 'connected', 'disconnected', and
64 // 'received' which will get invoked _serially_ when it's determined
65 // that we've connected (i.e., detected master), disconnected
66 // (i.e, detected no master), or received events from the master.
67 // The library reconnects with the master upon a disconnection.
68 //
69 // NOTE: All calls and events are dropped while disconnected.
70 class Mesos : public MesosBase
71 {
72 public:
73  // The credential will be used for authenticating with the master. Currently,
74  // only HTTP basic authentication is supported.
75  Mesos(const std::string& master,
76  ContentType contentType,
77  const std::function<void()>& connected,
78  const std::function<void()>& disconnected,
79  const std::function<void(const std::queue<Event>&)>& received,
80  const Option<Credential>& credential);
81 
82  // Delete copy constructor.
83  Mesos(const Mesos& other) = delete;
84 
85  // Delete assignment operator.
86  Mesos& operator=(const Mesos& other) = delete;
87 
88  ~Mesos() override;
89 
90  // Attempts to send a call to the master.
91  //
92  // The scheduler should only invoke this method once it has received the
93  // 'connected' callback. Otherwise, all calls would be dropped while
94  // disconnected.
95  //
96  // Some local validation of calls is performed which may generate
97  // events without ever being sent to the master. This includes when
98  // calls are sent but no master is currently detected (i.e., we're
99  // disconnected).
100  void send(const Call& call) override;
101 
102  // Attempts to send a call to the master, returning the response.
103  //
104  // The scheduler should only invoke this method once it has received the
105  // 'connected' callback. Otherwise, a `Failure` will be returned.
106  //
107  // Some local validation of calls is performed, and the request will not be
108  // sent to the master if the validation fails.
109  //
110  // A `Failure` will be returned on validation failures or if an error happens
111  // when sending the request to the master, e.g., a master disconnection, or a
112  // deserialization error.
113  //
114  // If it was possible to receive a response from the server, the returned
115  // object will contain the HTTP response status code.
116  //
117  // There are three cases to consider depending on the HTTP response status
118  // code:
119  //
120  // (1) '202 ACCEPTED': Indicates the call was accepted for processing and
121  // neither `APIResult::response` nor `APIResult::error` will be set.
122  //
123  // (2) '200 OK': Indicates the call completed successfully.
124  // `APIResult::response` will be set if the `scheduler::Call::Type`
125  // has a corresponding `scheduler::Response::Type`, `APIResult::error`
126  // will not be set.
127  //
128  // (3) For all other HTTP status codes, the `APIResult::response` field will
129  // not be set and the `APIResult::error` field may be set to provide more
130  // information.
131  //
132  // Note: This method cannot be used to send `SUBSCRIBE` calls, use `send()`
133  // instead.
134  process::Future<APIResult> call(const Call& callMessage) override;
135 
136  // Force a reconnection with the master.
137  //
138  // In the case of a one-way network partition, the connection between the
139  // scheduler and master might not necessarily break. If the scheduler detects
140  // a partition, due to lack of `HEARTBEAT` events (e.g., 5) within a time
141  // window, it can explicitly ask the library to force a reconnection with
142  // the master.
143  //
144  // This call would be ignored if the scheduler is already disconnected with
145  // the master (e.g., no new master has been elected). Otherwise, the scheduler
146  // would get a 'disconnected' callback followed by a 'connected' callback.
147  void reconnect() override;
148 
149 protected:
150  // NOTE: This constructor is used for testing.
151  Mesos(
152  const std::string& master,
153  ContentType contentType,
154  const std::function<void()>& connected,
155  const std::function<void()>& disconnected,
156  const std::function<void(const std::queue<Event>&)>& received,
157  const Option<Credential>& credential,
158  const Option<std::shared_ptr<mesos::master::detector::MasterDetector>>&
159  detector);
160 
161  // Stops the library so that:
162  // - No more calls can be sent to the master.
163  // - No more callbacks can be made to the scheduler. In some cases, there
164  // may be one additional callback if the library was in the middle of
165  // processing an event.
166  //
167  // NOTE: This is used for testing.
168  virtual void stop();
169 
170 private:
171  MesosProcess* process;
172 };
173 
174 } // namespace scheduler {
175 } // namespace v1 {
176 } // namespace mesos {
177 
178 #endif // __MESOS_V1_SCHEDULER_HPP__
ContentType
Definition: http.hpp:43
Definition: master.hpp:27
mesos::v1::scheduler::Call Call
Definition: mesos.hpp:2616
Definition: scheduler.hpp:70
mesos::v1::scheduler::Mesos Mesos
Definition: mesos.hpp:2618
Definition: spec.hpp:26
Definition: scheduler.hpp:49
Result< Process > process(pid_t pid)
Definition: freebsd.hpp:30
virtual ~MesosBase()
Definition: scheduler.hpp:53
Definition: future.hpp:58
Future< size_t > send(const int_fd &fd, const void *buf, size_t size)