Issue 5790 - Get ready for integration into Chromium

libadblockplus-android-settings/src/org/adblockplus/libadblockplus/android/settings/AdblockHelper.java

 /*
  * This file is part of Adblock Plus <https://adblockplus.org/>,
  * Copyright (C) 2006-present 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
@@ skipping 221 matching lines @@
   public int getCounter()
   {
     return referenceCounter.get();
   }
 
   /**
    * Register AdblockHelper engine client
    * @param asynchronous If `true` engines will be created in background thread without locking of
    *                     current thread. Use waitForReady() before getEngine() later.
    *                     If `false` locks current thread.
+   * @return if a new instance is allocated
    */
-  public synchronized void retain(boolean asynchronous)
+  public synchronized boolean retain(boolean asynchronous)

[sergei, 2017/09/28 08:29:03]

Could you please point to where and how it's actually used. I would like to
check that the approach is not racy.

[anton, 2017/09/28 09:08:39]

Java's `synchronized` token excludes mutiple thread to access the block
concurrently. The second thread will be just blocked.
Also `referenceCounter` is `Atomic` and it excludes race here too.

https://bitbucket.org/4ntoine/chrome4sdp/commits/3bcbeadc50affdf2592d35fdb93c...

```
        // synchronously (blocks the UI (providing bad UX) but allows to get
pointer)
        // improvement: do it async and wait for engine to be created and passed
when URL is about to load
        if (AdblockHelper.get().retain(false)) {
            // pass FilterEngine instance pointer to C++ side
            long ptr =
AdblockHelper.get().getEngine().getFilterEngine().getFilterEnginePtr(); // not
just getPointer(); !
            Log.w(TAG, "Adblock: Notify C++ FilterEngine is created (passing
pointer) " + ptr + " in thread " + Thread.currentThread());
            sendFilterEnginePointer(ptr);
        }
```

[sergei, 2017/09/28 09:33:05]

BTW, I plan to add an asynchronous version of creation of FilterEngine in Java
because it's what should actually be used and it's already available in C++,
will it be more convenient here?
I cannot evaluate it now because it's not clear how the initAdblock and
deinitAdblock are called. JIC, please take into account that if they are called
from different threads then it's possible that between "Log.w(TAG, "Adblock:
Notify C++ FilterEngine is created (passing pointer) " + ptr + " in thread " +
Thread.currentThread());" and "sendFilterEnginePointer(ptr);" we execute
`deinitAdblock` and afterwards continue with "sendFilterEnginePointer(ptr);". I
just hope that initAdblock and deinitAdblock are called only from the same
thread and, although it's not important maybe merely once at the start of the
app and at the finishing of the app.

I would like to come back to the topic later.

   {
+    boolean firstInstance = false;
+
     if (referenceCounter.getAndIncrement() == 0)
     {
+      firstInstance = true;
+
       if (!asynchronous)
       {
         createAdblock();
       }
       else
       {
         // latch is required for async (see `waitForReady()`)
         engineCreated = new CountDownLatch(1);
 
         new Thread(new Runnable()
         {
           @Override
           public void run()
           {
             createAdblock();
 
             // unlock waiting client thread
             engineCreated.countDown();
           }
         }).start();
       }
     }
+    return firstInstance;
   }
 
   /**
    * Unregister AdblockHelper engine client
+   * @return `true` if the last instance is destroyed
    */
-  public synchronized void release()
+  public synchronized boolean release()
   {
+    boolean lastInstance = false;
+
     if (referenceCounter.decrementAndGet() == 0)
     {
+      lastInstance = true;
+
       if (engineCreated != null)
       {
         // retained asynchronously
         waitForReady();
         disposeAdblock();
 
         // to unlock waiting client in waitForReady()
         engineCreated.countDown();
         engineCreated = null;
       }
       else
       {
         disposeAdblock();
       }
     }
+    return lastInstance;
   }
 }