bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/internal/Callback.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2012 IBM Corporation and others.
   3  *
   4  * This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License 2.0
   6  * which accompanies this distribution, and is available at
   7  * https://www.eclipse.org/legal/epl-2.0/
   8  *
   9  * SPDX-License-Identifier: EPL-2.0
  10  *
  11  * Contributors:
  12  *     IBM Corporation - initial API and implementation
  13  *******************************************************************************/
  14 package org.eclipse.swt.internal;
  15
  16 import java.lang.reflect.*;
  17 import java.util.function.*;
  18
  19 import org.eclipse.swt.*;
  20
  21 /**
  22  * Instances of this class represent entry points into Java
  23  * which can be invoked from operating system level callback
  24  * routines.
  25  * <p>
  26  * IMPORTANT: A callback is only valid when invoked on the
  27  * thread which created it. The results are undefined (and
  28  * typically bad) when a callback is passed out to the
  29  * operating system (or other code) in such a way that the
  30  * callback is called from a different thread.
  31  */
  32
  33 public class Callback {
  34
  35         Object object;
  36         String method, signature;
  37         int argCount;
  38         long address, errorResult;
  39         boolean isStatic, isArrayBased;
  40
  41         static final boolean is32Bit = C.PTR_SIZEOF == 4 ? true : false;
  42         static final String PTR_SIGNATURE = is32Bit ? "I" : "J"; //$NON-NLS-1$  //$NON-NLS-2$
  43         static final String SIGNATURE_0 = getSignature(0);
  44         static final String SIGNATURE_1 = getSignature(1);
  45         static final String SIGNATURE_2 = getSignature(2);
  46         static final String SIGNATURE_3 = getSignature(3);
  47         static final String SIGNATURE_4 = getSignature(4);
  48         static final String SIGNATURE_N = "(["+PTR_SIGNATURE+")"+PTR_SIGNATURE; //$NON-NLS-1$  //$NON-NLS-2$
  49
  50 /**
  51  * Constructs a new instance of this class given an object
  52  * to send the message to, a string naming the method to
  53  * invoke and an argument count. Note that, if the object
  54  * is an instance of <code>Class</code> it is assumed that
  55  * the method is a static method on that class.
  56  *
  57  * <p>Note, do not use this if the method arguments have a double, as arguments will be
  58  * shifted/corrupted. See Bug 510538. Instead use the following constructor: <br>
  59  * <code> Callback (Object, String, Type, Type [])</code></p>
  60  *
  61  * @param object the object to send the message to
  62  * @param method the name of the method to invoke
  63  * @param argCount the number of arguments that the method takes
  64  */
  65 public Callback (Object object, String method, int argCount) {
  66         this (object, method, argCount, false);
  67 }
  68
  69 /**
  70  * Constructs a new instance of this class given an object
  71  * to send the message to, a string naming the method to
  72  * invoke, an argument count and a flag indicating whether
  73  * or not the arguments will be passed in an array. Note
  74  * that, if the object is an instance of <code>Class</code>
  75  * it is assumed that the method is a static method on that
  76  * class.
  77  *
  78  * <p>Note, do not use this if the method arguments have a double, as arguments will be
  79  * shifted/corrupted. See Bug 510538. Instead use the following constructor: <br>
  80  * <code> Callback (Object, String, Type, Type [])</code></p>
  81  *
  82  * @param object the object to send the message to
  83  * @param method the name of the method to invoke
  84  * @param argCount the number of arguments that the method takes
  85  * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
  86  */
  87 public Callback (Object object, String method, int argCount, boolean isArrayBased) {
  88         this (object, method, argCount, isArrayBased, 0);
  89 }
  90
  91 /**
  92  * Constructs a new instance of this class given an object
  93  * to send the message to, a string naming the method to
  94  * invoke, an argument count, a flag indicating whether
  95  * or not the arguments will be passed in an array and a value
  96  * to return when an exception happens. Note that, if
  97  * the object is an instance of <code>Class</code>
  98  * it is assumed that the method is a static method on that
  99  * class.
 100  *
 101  * <p>Note, do not use this if the method arguments have a double, as arguments will be
 102  * shifted/corrupted. See Bug 510538. Instead use the following constructor: <br>
 103  * <code> Callback (Object, String, Type, Type [])</code></p>
 104  *
 105  * @param object the object to send the message to
 106  * @param method the name of the method to invoke
 107  * @param argCount the number of arguments that the method takes
 108  * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
 109  * @param errorResult the return value if the java code throws an exception
 110  */
 111 public Callback (Object object, String method, int argCount, boolean isArrayBased, long errorResult) {
 112
 113         /* Set the callback fields */
 114         this.object = object;
 115         this.method = method;
 116         this.argCount = argCount;
 117         this.isStatic = object instanceof Class;
 118         this.isArrayBased = isArrayBased;
 119         this.errorResult = errorResult;
 120
 121         /* Inline the common cases */
 122         if (isArrayBased) {
 123                 signature = SIGNATURE_N;
 124         } else {
 125                 switch (argCount) {
 126                         case 0: signature = SIGNATURE_0; break; //$NON-NLS-1$
 127                         case 1: signature = SIGNATURE_1; break; //$NON-NLS-1$
 128                         case 2: signature = SIGNATURE_2; break; //$NON-NLS-1$
 129                         case 3: signature = SIGNATURE_3; break; //$NON-NLS-1$
 130                         case 4: signature = SIGNATURE_4; break; //$NON-NLS-1$
 131                         default:
 132                                 signature = getSignature(argCount);
 133                 }
 134         }
 135
 136         /* Bind the address */
 137         address = bind (this, object, method, signature, argCount, isStatic, isArrayBased, errorResult);
 138 }
 139
 140
 141 /**
 142  * <p>Register the java method to be a C callback.
 143  * I.e, C will be able to make a call to this java method directly (through callback.c)</p>
 144  *
 145  * <p>The other constructors hard-code int/long into the method signature:<br>
 146  * <code> long method (long ...) </code><br>
 147  * Which is suitable for int/long and pointers.<br>
 148  * This constructor is used if you need to use a different return/argument type, e.g double. See Bug 510538 </p>
 149  *
 150  * <p> Note:
 151  * <ul>
 152  * <li> Array support is not implemented/supported by this constructor. Use other constructors.</li>
 153  * <li> If the object is an instance of <code>Class</code> it is assumed that
 154  * the method is a static method on that class. </li>
 155  * <li> Note, long types are converted to ints on 32 bit system automatically to account for smaller pointers.
 156  * This means if you use 'long', you need to cast int next to it. like: <code> long &#47;*int*&#47;</code> </li>
 157  * </ul></p>
 158  *
 159  * <p>The following types are supported: <br>
 160  * <ul>
 161  * <li>void (for return values only) </li>
 162  * <li>int</li>
 163  * <li>long</li>
 164  * <li>byte</li>
 165  * <li>char</li>
 166  * <li>double</li>
 167  * <li>float</li>
 168  * <li>short</li>
 169  * <li>boolean</li>
 170  * </ul>
 171  *
 172  * <p> For example if you want to link the following method: <br>
 173  * <code> void myMethod(long &#47;*int*&#47; arg1, double arg2) </code> <br>
 174  * Then you would call this callback like:<br>
 175  * <code> Callback (this, "myMethod", void.class, new Type []{long.class, double.class}); </code>
 176  * </p>
 177  *
 178  * @param object the object to send the message to
 179  * @param method method the name of the method to invoke
 180  * @param returnType specify the type like  <code>void.class, long.class, double.class </code>
 181  * @param arguments specify the list of arguments like <code> new Type [] {long.class, double.class } </code>
 182  */
 183 public Callback (Object object, String method, Type returnType, Type [] arguments) {
 184         /* Set the callback fields */
 185         this.object = object;
 186         this.method = method;
 187         this.argCount = arguments != null ? arguments.length : 0;
 188         this.isStatic = object instanceof Class;
 189         this.isArrayBased = false;
 190         this.errorResult = 0;
 191
 192         Function <Type, String> getTypeLetter = type -> {
 193                 // https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3.2
 194                 if (int.class.equals(type)) {
 195                         return "I";
 196                 } else if (long.class.equals(type)) {
 197                         return "J";
 198                 } else if (void.class.equals(type)) { // for return type.
 199                         return "V";
 200                 } else if (byte.class.equals(type)) {
 201                         return "B";
 202                 } else if (char.class.equals(type)) {
 203                         return "C";
 204                 } else if (double.class.equals(type)) {
 205                         return "D";
 206                 } else if (float.class.equals(type)) {
 207                         return "F";
 208                 } else if (short.class.equals(type)) {
 209                         return "S";
 210                 } else if (boolean.class.equals(type)) {
 211                         return "Z";
 212                 }
 213                 SWT.error(SWT.ERROR_INVALID_ARGUMENT, null, type.toString() + "Not supported");
 214                 return null; // not reachable. Suppress warning.
 215         };
 216
 217         StringBuilder signature = new StringBuilder("(");
 218         for (Type t : arguments) {
 219                 if (t.equals(void.class)) {
 220                         SWT.error(SWT.ERROR_INVALID_ARGUMENT, null, "void is not a valid argument");
 221                 }
 222                 signature.append(getTypeLetter.apply(t));
 223         }
 224         signature.append(")");
 225         signature.append(getTypeLetter.apply(returnType));
 226         this.signature = signature.toString();
 227         if (is32Bit) {
 228                 this.signature = this.signature.replace("J", "I");
 229         }
 230
 231         /* Bind the address */
 232         address = bind (this, this.object, this.method, this.signature, this.argCount, this.isStatic, this.isArrayBased, this.errorResult);
 233 }
 234
 235
 236
 237 /**
 238  * Allocates the native level resources associated with the
 239  * callback. This method is only invoked from within the
 240  * constructor for the argument.
 241  *
 242  * @param callback the callback to bind
 243  * @param object the callback's object
 244  * @param method the callback's method
 245  * @param signature the callback's method signature
 246  * @param argCount the callback's method argument count
 247  * @param isStatic whether the callback's method is static
 248  * @param isArrayBased whether the callback's method is array based
 249  * @param errorResult the callback's error result
 250  */
 251 static native synchronized long bind (Callback callback, Object object, String method, String signature, int argCount, boolean isStatic, boolean isArrayBased, long errorResult);
 252
 253 /**
 254  * Releases the native level resources associated with the callback,
 255  * and removes all references between the callback and
 256  * other objects. This helps to prevent (bad) application code
 257  * from accidentally holding onto extraneous garbage.
 258  */
 259 public void dispose () {
 260         if (object == null) return;
 261         unbind (this);
 262         object = method = signature = null;
 263         address = 0;
 264 }
 265
 266 /**
 267  * Returns the address of a block of machine code which will
 268  * invoke the callback represented by the receiver.
 269  *
 270  * @return the callback address
 271  */
 272 public long getAddress () {
 273         return address;
 274 }
 275
 276 /**
 277  * Returns the SWT platform name.
 278  *
 279  * @return the platform name of the currently running SWT
 280  */
 281 public static native String getPlatform ();
 282
 283 /**
 284  * Returns the number of times the system has been recursively entered
 285  * through a callback.
 286  * <p>
 287  * Note: This should not be called by application code.
 288  * </p>
 289  *
 290  * @return the entry count
 291  *
 292  * @since 2.1
 293  */
 294 public static native int getEntryCount ();
 295
 296 static String getSignature(int argCount) {
 297         String signature = "("; //$NON-NLS-1$
 298         for (int i = 0; i < argCount; i++) signature += PTR_SIGNATURE;
 299         signature += ")" + PTR_SIGNATURE; //$NON-NLS-1$
 300         return signature;
 301 }
 302
 303 /**
 304  * Indicates whether or not callbacks which are triggered at the
 305  * native level should cause the messages described by the matching
 306  * <code>Callback</code> objects to be invoked. This method is used
 307  * to safely shut down SWT when it is run within environments
 308  * which can generate spurious events.
 309  * <p>
 310  * Note: This should not be called by application code.
 311  * </p>
 312  *
 313  * @param enable true if callbacks should be invoked
 314  */
 315 public static final native synchronized void setEnabled (boolean enable);
 316
 317 /**
 318  * Returns whether or not callbacks which are triggered at the
 319  * native level should cause the messages described by the matching
 320  * <code>Callback</code> objects to be invoked. This method is used
 321  * to safely shut down SWT when it is run within environments
 322  * which can generate spurious events.
 323  * <p>
 324  * Note: This should not be called by application code.
 325  * </p>
 326  *
 327  * @return true if callbacks should not be invoked
 328  */
 329 public static final native synchronized boolean getEnabled ();
 330
 331 /**
 332  * This might be called directly from native code in environments
 333  * which can generate spurious events. Check before removing it.
 334  *
 335  * @deprecated
 336  *
 337  * @param ignore true if callbacks should not be invoked
 338  */
 339 @Deprecated
 340 static final void ignoreCallbacks (boolean ignore) {
 341         setEnabled (!ignore);
 342 }
 343
 344 /**
 345  * Immediately wipes out all native level state associated
 346  * with <em>all</em> callbacks.
 347  * <p>
 348  * <b>WARNING:</b> This operation is <em>extremely</em> dangerous,
 349  * and should never be performed by application code.
 350  * </p>
 351  */
 352 public static final native synchronized void reset ();
 353
 354 /**
 355  * Releases the native level resources associated with the callback.
 356  *
 357  * @see #dispose
 358  */
 359 static final native synchronized void unbind (Callback callback);
 360
 361 }