Issue 5450 - introduce the Platform class

include/AdblockPlus/Platform.h

Index: include/AdblockPlus/Platform.h
diff --git a/include/AdblockPlus/Platform.h b/include/AdblockPlus/Platform.h
new file mode 100644
index 0000000000000000000000000000000000000000..efcae83bde90c28956c3376553658df26f8eb481
--- /dev/null
+++ b/include/AdblockPlus/Platform.h
@@ -0,0 +1,133 @@
+/*
+ * This file is part of Adblock Plus <https://adblockplus.org/>,
+ * Copyright (C) 2006-2017 eyeo GmbH
+ *
+ * Adblock Plus is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * Adblock Plus is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef ADBLOCK_PLUS_PLATFORM_H
+#define ADBLOCK_PLUS_PLATFORM_H
+
+#include "LogSystem.h"
+#include "ITimer.h"
+#include "IFileSystem.h"
+#include "IWebRequest.h"
+#include "AppInfo.h"
+#include "Scheduler.h"
+#include <mutex>
+
+namespace AdblockPlus
+{
+  /**
+   * A factory to construct DefaultTimer.
+   */
+  TimerPtr CreateDefaultTimer();
+
+  /**
+   * A factory to construct DefaultFileSystem.
+   */
+  FileSystemPtr CreateDefaultFileSystem(const Scheduler& scheduler);
+
+  /**
+   * A factory to construct DefaultWebRequest.
+   */
+  WebRequestPtr CreateDefaultWebRequest(const Scheduler& scheduler);
+
+  /**
+   * A factory to construct LogSystem.
+   */
+  LogSystemPtr CreateDefaultLogSystem();
+
+  class JsEngine;
+
+  /**
+   * AdblockPlus platform is the main component providing access to other
+   * modules.
+   *
+   * It manages the functionality modules, e.g. JsEngine and FilterEngine as
+   * well as allows to correctly work with asynchronous functionality.
+   */
+  class Platform
+  {
+  public:
+    /**
+     * Platform creation parameters.
+     *
+     * @param logSystem Implementation of log system.
+     * @param timer Implementation of timer.
+     * @param webRequest Implementation of web request.
+     * @param fileSystem Implementation of filesystem.
+     */
+    struct CreationParameters
+    {
+      LogSystemPtr logSystem;
+      TimerPtr timer;
+      WebRequestPtr webRequest;
+      FileSystemPtr fileSystem;
+    };
+
+    /**
+     * Platform constructor.
+     *
+     * When a parameter value is nullptr the corresponding default
+     * implementation is chosen.
+     */
+    explicit Platform(CreationParameters&& creationParameters = CreationParameters());
+    ~Platform();
+
+    /**
+     * Ensures that JsEngine is constructed.
+     *
+     * @param appInfo Information about the app, if jsEngine is already present
+     *        then the value is ignored.
+     */
+    void SetUpJsEngine(const AppInfo& appInfo = AppInfo());
+
+    /**
+     * Retrieves the `JsEngine` instance. It calls SetUpJsEngine if JsEngine is
+     * not initialized yet.
+     */
+    std::shared_ptr<JsEngine> GetJsEngine();

[hub, 2017/08/04 14:18:43]

I thought we had settled on returning a JsEngine& here.

[sergei, 2017/08/04 14:40:09]

We cannot do it right now because a lot of other code depends on it. I have
prepared changes firstly moving FilterEngine into Platform and then changing
this return value as well as a return value of GetFilterEngine to the
references. Meanwhile one can find them in
https://github.com/abby-sergz/libadblockplus/commits/ci-5450-references-api, I'm
going to send them to codereview after landing of this codereview.

BTW, there will still be a way to misuse it with JsValue:
JsValue jsValue = Plaltform().GetFilterEngine().GetPref("some pref");
or
JsValue jsValue = Plaltform().GetJsEngine().NewValue("some string");
jsValue.someMethod(); // here Platform with all internals is already destroyed.
I think we should simply say that it's not allowed to use anything after
destroying of Platform.

[hub, 2017/08/04 15:14:49]

yes it is not bullet proof. Lifetime is not an easy problem, but just forbidding
it in the documentation isn't enough.

+
+    /**
+    * @return The asynchronous ITimer implementation.
+     */
+    ITimer& GetTimer();
+
+    /**
+     * @return The asynchronous IFileSystem implementation.
+     */
+    IFileSystem& GetFileSystem();
+
+    /**
+    * @return The asynchronous IWebRequest implementation.
+    */
+    IWebRequest& GetWebRequest();
+
+    /**
+     * @see `SetLogSystem()`.
+     */
+    LogSystem& GetLogSystem();
+
+  private:
+    LogSystemPtr logSystem;
+    TimerPtr timer;
+    FileSystemPtr fileSystem;
+    WebRequestPtr webRequest;
+    // used for creation and deletion of modules.
+    std::mutex modulesMutex;
+    std::shared_ptr<JsEngine> jsEngine;

[hub, 2017/08/04 14:18:43]

...Which would make this a unique_ptr<JsEngine>

[sergei, 2017/08/04 14:40:09]

This case is also a bit complicated, firstly we should get rid of
std::shared_ptr<JsEngine> everywhere in the code. I think it can be done later
in parallel.

BTW, having a shared pointer here can help to implement showing of a warning
when Platform is already destroyed but someone is still having a reference to
JsEngine, as we discussed somewhere.

[hub, 2017/08/04 15:14:49]

That suggestion was depending on the one above. Platform own the JsEngine.

+  };
+}
+
+#endif // ADBLOCK_PLUS_PLATFORM_H