/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package com.apple.concurrent;

import java.util.concurrent.*;

/**

 * Factory for {@link Executor}s and {@link ExecutorService}s backed by

 * libdispatch.

 *

 * Access is controlled through the Dispatch.getInstance() method, because

 * performed tasks occur on threads owned by libdispatch. These threads are

 * not owned by any particular AppContext or have any specific context

 * classloader installed.

 *

 * @since Java for Mac OS X 10.6 Update 2

 */

public final class Dispatch {

        /**

         * The priorities of the three default asynchronous queues.

         */

        public enum Priority {

                LOW(-2), NORMAL(0), HIGH(2); // values from <dispatch/queue.h>

                final int nativePriority;

                Priority(final int nativePriority) { this.nativePriority = nativePriority; }

        };

        final static Dispatch instance = new Dispatch();

        /**

         * Factory method returns an instnace of Dispatch if supported by the

         * underlying operating system, and if the caller's security manager

         * permits "canInvokeInSystemThreadGroup".

         *

         * @return a factory instance of Dispatch, or null if not available

         */

        public static Dispatch getInstance() {

                checkSecurity();

                if (!LibDispatchNative.nativeIsDispatchSupported()) return null;

                return instance;

        }

        private static void checkSecurity() {

        final SecurityManager security = System.getSecurityManager();

        if (security != null) security.checkPermission(new RuntimePermission("canInvokeInSystemThreadGroup"));

    }

        private Dispatch() { }

        /**

         * Creates an {@link Executor} that performs tasks asynchronously. The {@link Executor}

         * cannot be shutdown, and enqueued {@link Runnable}s cannot be canceled. Passing null

         * returns the {@link Priority.NORMAL} {@link Executor}.

         *

         * @param priority - the priority of the returned {@link Executor}

         * @return an asynchronous {@link Executor}

         */

        public Executor getAsyncExecutor(Priority priority) {

                if (priority == null) priority = Priority.NORMAL;

                final long nativeQueue = LibDispatchNative.nativeCreateConcurrentQueue(priority.nativePriority);

                if (nativeQueue == 0L) return null;

                return new LibDispatchConcurrentQueue(nativeQueue);

        }

        int queueIndex = 0;

        /**

         * Creates an {@link ExecutorService} that performs tasks synchronously in FIFO order.

         * Useful to protect a resource against concurrent modification, in lieu of a lock.

         * Passing null returns an {@link ExecutorService} with a uniquely labeled queue.

         *

         * @param label - a label to name the queue, shown in several debugging tools

         * @return a synchronous {@link ExecutorService}

         */

        public ExecutorService createSerialExecutor(String label) {

                if (label == null) label = "";

                if (label.length() > 256) label = label.substring(0, 256);

                String queueName = "com.apple.java.concurrent.";

                if ("".equals(label)) {

                        synchronized (this) {

                                queueName += queueIndex++;

                        }

                } else {

                        queueName += label;

                }

                final long nativeQueue = LibDispatchNative.nativeCreateSerialQueue(queueName);

                if (nativeQueue == 0) return null;

                return new LibDispatchSerialQueue(nativeQueue);

        }

        Executor nonBlockingMainQueue = null;

        /**

         * Returns an {@link Executor} that performs the provided Runnables on the main queue of the process.

         * Runnables submitted to this {@link Executor} will not run until the AWT is started or another native toolkit is running a CFRunLoop or NSRunLoop on the main thread.

         *

         * Submitting a Runnable to this {@link Executor} does not wait for the Runnable to complete.

         * @return an asynchronous {@link Executor} that is backed by the main queue

         */

        public synchronized Executor getNonBlockingMainQueueExecutor() {

                if (nonBlockingMainQueue != null) return nonBlockingMainQueue;

                return nonBlockingMainQueue = new LibDispatchMainQueue.ASync();

        }

        Executor blockingMainQueue = null;

        /**

         * Returns an {@link Executor} that performs the provided Runnables on the main queue of the process.

         * Runnables submitted to this {@link Executor} will not run until the AWT is started or another native toolkit is running a CFRunLoop or NSRunLoop on the main thread.

         *

         * Submitting a Runnable to this {@link Executor} will block until the Runnable has completed.

         * @return an {@link Executor} that is backed by the main queue

         */

        public synchronized Executor getBlockingMainQueueExecutor() {

                if (blockingMainQueue != null) return blockingMainQueue;

                return blockingMainQueue = new LibDispatchMainQueue.Sync();

        }

}