/*
* Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
* 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();
}
}