datasrc_clients_mgr.h 17.7 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Copyright (C) 2012  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#ifndef DATASRC_CLIENTS_MGR_H
#define DATASRC_CLIENTS_MGR_H 1

18
#include <util/threads/thread.h>
19
#include <util/threads/sync.h>
20

21
22
23
#include <log/logger_support.h>
#include <log/log_dbglevels.h>

24
#include <auth/datasrc_config.h>
25
#include <cc/data.h>
26
27
#include <datasrc/client_list.h>
#include <dns/rrclass.h>
28

29
#include <auth/auth_log.h>
30
#include <auth/datasrc_config.h>
31

32
#include <boost/array.hpp>
33
#include <boost/bind.hpp>
34
#include <boost/shared_ptr.hpp>
35
#include <boost/noncopyable.hpp>
36

37
38
39
40
41
42
#include <list>
#include <utility>

namespace isc {
namespace auth {

43
namespace datasrc_clientmgr_internal {
44
45
46
47
48
49
// This namespace is essentially private for DataSrcClientsMgr(Base) and
// DataSrcClientsBuilder(Base).  This is exposed in the public header
// only because these classes are templated (for testing purposes) and
// class internal has to be defined here.

/// \brief ID of commands from the DataSrcClientsMgr to DataSrcClientsBuilder.
50
enum CommandID {
51
    NOOP,         ///< Do nothing.  Only useful for tests; no argument
52
    RECONFIGURE,  ///< Reconfigure the datasource client lists, configuration argument (TODO: describe here?)
53
54
    SHUTDOWN,     ///< Shutdown the builder; no argument
    NUM_COMMANDS
55
};
56
57
58
59
60
61
62

/// \brief The data type passed from DataSrcClientsMgr to
/// DataSrcClientsBuilder.
///
/// The first element of the pair is the command ID, and the second element
/// is its argument.  If the command doesn't take an argument it should be
/// a null pointer.
63
typedef std::pair<CommandID, data::ConstElementPtr> Command;
64
} // namespace datasrc_clientmgr_internal
65

66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
/// \brief Frontend to the manager object for data source clients.
///
/// This class provides interfaces for configuring and updating a set of
/// data source clients "in the background".  The user of this class can
/// assume any operation on this class can be done effectively non-blocking,
/// not suspending any delay-sensitive operations such as DNS query
/// processing.  The only exception is the time when this class object
/// is destroyed (normally as a result of an implicit call to the destructor);
/// in the current implementation it can take time depending on what is
/// running "in the background" at the time of the call.
///
/// Internally, an object of this class invokes a separate thread to perform
/// time consuming operations such as loading large zone data into memory,
/// but such details are completely hidden from the user of this class.
///
/// This class is templated only so that we can test the class without
/// involving actual threads or mutex.  Normal applications will only
/// need one specific specialization that has a typedef of
/// \c DataSrcClientsMgr.
85
86
template <typename ThreadType, typename BuilderType, typename MutexType,
          typename CondVarType>
87
class DataSrcClientsMgrBase : boost::noncopyable {
88
89
90
91
92
private:
    typedef std::map<dns::RRClass,
                     boost::shared_ptr<datasrc::ConfigurableClientList> >
    ClientListsMap;

93
public:
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
    /// \brief Thread-safe accessor to the data source client lists.
    ///
    /// This class provides a simple wrapper for searching the client lists
    /// stored in the DataSrcClientsMgr in a thread-safe manner.
    /// It ensures the result of \c getClientList() can be used without
    /// causing a race condition with other threads that can possibly use
    /// the same manager throughout the lifetime of the holder object.
    ///
    /// This also means the holder object is expected to have a short lifetime.
    /// The application shouldn't try to keep it unnecessarily long.
    /// It's normally expected to create the holder object on the stack
    /// of a small scope and automatically let it be destroyed at the end
    /// of the scope.
    class Holder {
    public:
        Holder(DataSrcClientsMgrBase& mgr) :
            mgr_(mgr), locker_(mgr_.map_mutex_)
        {}

        /// \brief Find a data source client list of a specified RR class.
        ///
        /// It returns a pointer to the list stored in the manager if found,
        /// otherwise it returns NULL.  The manager keeps the ownership of
        /// the pointed object.  Also, it's not safe to get access to the
        /// object beyond the scope of the holder object.
119
120
121
122
123
124
125
126
127
        ///
        /// \note Since the ownership isn't transferred the return value
        /// could be a bare pointer (and it's probably better in several
        /// points).  Unfortunately, some unit tests currently don't work
        /// unless this method effectively shares the ownership with the
        /// tests.  That's the only reason why we return a shared pointer
        /// for now.  We should eventually fix it and change the return value
        /// type (see Trac ticket #2395).  Other applications must not
        /// assume the ownership is actually shared.
128
        boost::shared_ptr<datasrc::ConfigurableClientList> findClientList(
129
130
131
132
133
            const dns::RRClass& rrclass)
        {
            const ClientListsMap::const_iterator
                it = mgr_.clients_map_->find(rrclass);
            if (it == mgr_.clients_map_->end()) {
134
                return (boost::shared_ptr<datasrc::ConfigurableClientList>());
135
            } else {
136
                return (it->second);
137
138
139
140
141
142
143
            }
        }
    private:
        DataSrcClientsMgrBase& mgr_;
        typename MutexType::Locker locker_;
    };

144
145
146
147
148
149
150
151
152
153
154
155
    /// \brief Constructor.
    ///
    /// It internally invokes a separate thread and waits for further
    /// operations from the user application.
    ///
    /// This method is basically exception free except in case of really
    /// rare system-level errors.  When that happens the only reasonable
    /// action that the application can take would be to terminate the program
    /// in practice.
    ///
    /// \throw std::bad_alloc internal memory allocation failure.
    /// \throw isc::Unexpected general unexpected system errors.
156
    DataSrcClientsMgrBase() :
157
        clients_map_(new ClientListsMap),
Jelte Jansen's avatar
Jelte Jansen committed
158
159
        builder_(&command_queue_, &cond_, &queue_mutex_, &clients_map_,
                 &map_mutex_),
160
        builder_thread_(boost::bind(&BuilderType::run, &builder_))
161
    {}
162
163
164
165
166
167
168
169
170
171
172
173

    /// \brief The destructor.
    ///
    /// It tells the internal thread to stop and waits for it completion.
    /// In the current implementation, it can block for some unpredictably
    /// long period depending on what the thread is doing at that time
    /// (in future we may want to implement a rapid way of killing the thread
    /// and/or provide a separate interface for waiting so that the application
    /// can choose the timing).
    ///
    /// The waiting operation can result in an exception, but this method
    /// catches any of them so this method itself is exception free.
174
    ~DataSrcClientsMgrBase() {
175
176
177
        // We share class member variables with the builder, which will be
        // invalidated after the call to the destructor, so we need to make
        // sure the builder thread is terminated.  Depending on the timing
178
179
180
        // this could take a long time; if we don't want that to happen in
        // this context, we may want to introduce a separate 'shutdown()'
        // method.
181
182
183
184
        // Also, since we don't want to propagate exceptions from a destructor,
        // we catch any possible ones.  In fact the only really expected one
        // is Thread::UncaughtException when the builder thread died due to
        // an exception.  We specifically log it and just ignore others.
185
        try {
186
187
            sendCommand(datasrc_clientmgr_internal::SHUTDOWN,
                        data::ConstElementPtr());
188
            builder_thread_.wait();
189
        } catch (const util::thread::Thread::UncaughtException& ex) {
190
191
192
            // technically, logging this could throw, which will be propagated.
            // But such an exception would be a fatal one anyway, so we
            // simply let it go through.
193
194
            LOG_ERROR(auth_logger, AUTH_DATASRC_CLIENTS_SHUTDOWN_ERROR).
                arg(ex.what());
195
196
197
198
        } catch (...) {
            LOG_ERROR(auth_logger,
                      AUTH_DATASRC_CLIENTS_SHUTDOWN_UNEXPECTED_ERROR);
        }
199
200

        cleanup();              // see below
201
202
    }

203
204
205
206
    /// \brief Handle new full configuration for data source clients.
    ///
    /// This method simply passes the new configuration to the builder
    /// and immediately returns.  This method is basically exception free
207
208
    /// as long as the caller passes a non NULL value for \c config_arg;
    /// it doesn't validate the argument further.
209
210
211
212
213
214
215
216
217
218
    ///
    /// \brief isc::InvalidParameter config_arg is NULL.
    /// \brief std::bad_alloc
    ///
    /// \param config_arg The new data source configuration.  Must not be NULL.
    void reconfigure(data::ConstElementPtr config_arg) {
        if (!config_arg) {
            isc_throw(InvalidParameter, "Invalid null config argument");
        }
        sendCommand(datasrc_clientmgr_internal::RECONFIGURE, config_arg);
219
        reconfigureHook();      // for test's customization
220
221
    }

222
    /// \brief Set the underlying data source client lists to new lists.
223
224
225
226
    ///
    /// This is provided only for some existing tests until we support a
    /// cleaner way to use faked data source clients.  Non test code or
    /// newer tests must not use this.
227
    void setDataSrcClientLists(datasrc::DataSrcClientListsPtr new_lists) {
228
        typename MutexType::Locker locker(map_mutex_);
229
        clients_map_ = new_lists;
230
231
    }

232
private:
233
234
235
236
237
238
    // This is expected to be called at the end of the destructor.  It
    // actually does nothing, but provides a customization point for
    // specialized class for tests so that the tests can inspect the last
    // state of the class.
    void cleanup() {}

239
240
241
    // same as cleanup(), for reconfigure().
    void reconfigureHook() {}

242
    void sendCommand(datasrc_clientmgr_internal::CommandID command,
243
244
                     data::ConstElementPtr arg)
    {
245
246
247
248
249
250
        // The lock will be held until the end of this method.  Only
        // push_back has to be protected, but we can avoid having an extra
        // block this way.
        typename MutexType::Locker locker(queue_mutex_);
        command_queue_.push_back(
            datasrc_clientmgr_internal::Command(command, arg));
251
        cond_.signal();
252
    }
253

254
255
256
257
    //
    // The following are shared with the builder.
    //
    // The list is used as a one-way queue: back-in, front-out
258
    std::list<datasrc_clientmgr_internal::Command> command_queue_;
259
260
    CondVarType cond_;          // condition variable for queue operations
    MutexType queue_mutex_;     // mutex to protect the queue
261
    isc::datasrc::DataSrcClientListsPtr clients_map_;
262
263
    MutexType map_mutex_;

264
    BuilderType builder_;
265
    ThreadType builder_thread_; // for safety this should be placed last
266
267
};

268
namespace datasrc_clientmgr_internal {
269
270
271
272
273

/// \brief A class that maintains a set of data source clients.
///
/// An object of this class is supposed to run on a dedicated thread, whose
/// main function is a call to its \c run() method.  It runs in a loop
274
/// waiting for commands from the manager and handles each command (including
275
/// reloading a new version of zone data into memory or fully reconfiguration
276
/// of specific set of data source clients).  When it receives a SHUTDOWN
277
278
/// command, it exits from the loop, which will terminate the thread.
///
279
280
281
/// While this class is defined in a publicly visible namespace, it's
/// essentially private to \c DataSrcClientsMgr.  Except for tests,
/// applications should not directly access this class.
282
283
284
///
/// This class is templated so that we can test it without involving actual
/// threads or locks.
285
template <typename MutexType, typename CondVarType>
286
class DataSrcClientsBuilderBase : boost::noncopyable {
287
public:
288
289
290
291
292
293
294
295
    /// \brief Constructor.
    ///
    /// It simply sets up a local copy of shared data with the manager.
    ///
    /// Note: this will take actual set (map) of data source clients and
    /// a mutex object for it in #2210 or #2212.
    ///
    /// \throw None
296
    DataSrcClientsBuilderBase(std::list<Command>* command_queue,
297
                              CondVarType* cond, MutexType* queue_mutex,
298
                              isc::datasrc::DataSrcClientListsPtr* clients_map,
299
                              MutexType* map_mutex
300
        ) :
301
302
        command_queue_(command_queue), cond_(cond), queue_mutex_(queue_mutex),
        clients_map_(clients_map), map_mutex_(map_mutex)
303
304
    {}

305
    /// \brief The main loop.
306
307
    void run();

308
309
310
311
312
313
    /// \brief Handle one command from the manager.
    ///
    /// This is a dedicated subroutine of run() and is essentially private,
    /// but is defined as a separate public method so we can test each
    /// command test individually.  In any case, this class itself is
    /// generally considered private.
314
    ///
315
    /// \return true if the builder should keep running; false otherwise.
316
317
318
    bool handleCommand(const Command& command);

private:
319
320
    // NOOP command handler.  We use this so tests can override it; the default
    // implementation really does nothing.
321
322
    void doNoop() {}

323
324
325
    void doReconfigure(const isc::data::ConstElementPtr& config) {
        if (config) {
            try {
326
                isc::datasrc::DataSrcClientListsPtr new_clients_map =
327
328
329
                    configureDataSource(config);
                typename MutexType::Locker locker(*map_mutex_);
                std::swap(new_clients_map, *clients_map_);
Jelte Jansen's avatar
Jelte Jansen committed
330
                // lock is released by leaving scope
331
            } catch (const isc::data::TypeError& type_error) {
Jelte Jansen's avatar
Jelte Jansen committed
332
333
334
                LOG_ERROR(auth_logger,
                    AUTH_DATASRC_CLIENTS_BUILDER_RECONFIGURE_CONFIG_ERROR).
                    arg(type_error.what());
335
            } catch (const std::exception& exc) {
Jelte Jansen's avatar
Jelte Jansen committed
336
337
338
                LOG_ERROR(auth_logger,
                    AUTH_DATASRC_CLIENTS_BUILDER_RECONFIGURE_ERROR).
                    arg(exc.what());
339
            } catch (...) {
Jelte Jansen's avatar
Jelte Jansen committed
340
341
                LOG_ERROR(auth_logger,
                    AUTH_DATASRC_CLIENTS_BUILDER_RECONFIGURE_UNKNOWN_ERROR);
342
343
344
345
            }
        }
    }

346
    // The following are shared with the manager
347
348
349
    std::list<Command>* command_queue_;
    CondVarType* cond_;
    MutexType* queue_mutex_;
350
    isc::datasrc::DataSrcClientListsPtr* clients_map_;
351
    MutexType* map_mutex_;
352
353
354
355
356
357
};

// Shortcut typedef for normal use
typedef DataSrcClientsBuilderBase<util::thread::Mutex, util::thread::CondVar>
DataSrcClientsBuilder;

358
359
360
template <typename MutexType, typename CondVarType>
void
DataSrcClientsBuilderBase<MutexType, CondVarType>::run() {
361
    LOG_INFO(auth_logger, AUTH_DATASRC_CLIENTS_BUILDER_STARTED);
362

363
364
365
366
367
368
    try {
        bool keep_running = true;
        while (keep_running) {
            std::list<Command> current_commands;
            {
                // Move all new commands to local queue under the protection of
369
                // queue_mutex_.
370
371
372
373
                typename MutexType::Locker locker(*queue_mutex_);
                while (command_queue_->empty()) {
                    cond_->wait(*queue_mutex_);
                }
374
                current_commands.swap(*command_queue_);
375
376
377
378
379
            } // the lock is release here.

            while (keep_running && !current_commands.empty()) {
                keep_running = handleCommand(current_commands.front());
                current_commands.pop_front();
380
381
            }
        }
382

383
384
385
        LOG_INFO(auth_logger, AUTH_DATASRC_CLIENTS_BUILDER_STOPPED);
    } catch (const std::exception& ex) {
        // We explicitly catch exceptions so we can log it as soon as possible.
386
        LOG_FATAL(auth_logger, AUTH_DATASRC_CLIENTS_BUILDER_FAILED).
387
            arg(ex.what());
388
        assert(false);
389
    } catch (...) {
390
        LOG_FATAL(auth_logger, AUTH_DATASRC_CLIENTS_BUILDER_FAILED_UNEXPECTED);
391
        assert(false);
392
    }
393
394
395
396
397
398
399
}

template <typename MutexType, typename CondVarType>
bool
DataSrcClientsBuilderBase<MutexType, CondVarType>::handleCommand(
    const Command& command)
{
400
401
402
403
404
    const CommandID cid = command.first;
    if (cid >= NUM_COMMANDS) {
        // This shouldn't happen except for a bug within this file.
        isc_throw(Unexpected, "internal bug: invalid command, ID: " << cid);
    }
405

406
    const boost::array<const char*, NUM_COMMANDS> command_desc = {
407
        {"NOOP", "RECONFIGURE", "SHUTDOWN"}
408
409
410
    };
    LOG_DEBUG(auth_logger, DBGLVL_TRACE_BASIC,
              AUTH_DATASRC_CLIENTS_BUILDER_COMMAND).arg(command_desc.at(cid));
411
    switch (command.first) {
412
413
414
    case RECONFIGURE:
        doReconfigure(command.second);
        break;
415
416
417
418
    case SHUTDOWN:
        return (false);
    case NOOP:
        doNoop();
419
420
421
        break;
    case NUM_COMMANDS:
        assert(false);          // we rejected this case above
422
423
424
    }
    return (true);
}
425
} // namespace datasrc_clientmgr_internal
426
427
428
429
430

/// \brief Shortcut type for normal data source clients manager.
///
/// In fact, for non test applications this is the only type of this kind
/// to be considered.
431
432
433
434
typedef DataSrcClientsMgrBase<
    util::thread::Thread,
    datasrc_clientmgr_internal::DataSrcClientsBuilder,
    util::thread::Mutex, util::thread::CondVar> DataSrcClientsMgr;
435
436
437
438
439
440
441
442
} // namespace auth
} // namespace isc

#endif  // DATASRC_CLIENTS_MGR_H

// Local Variables:
// mode: c++
// End: