docs/devel/mji/mangling.md

   1 # Mangling for MJI #
   2 ## Mangling Methods ##
   3 Suppose your method looks like
   4
   5 ~~~~~~~~ {.java}
   6 T1 foo(T2 x, T3 y, ...)
   7 ~~~~~~~~
   8
   9 where the `Ti` are Java types.
  10
  11 If `T1` is a primitive type or `void`, then the mangled MJI method looks
  12 like
  13
  14 ~~~~~~~~ {.java}
  15 public static T1 foo__MT2MT3...__MT1(...)
  16 ~~~~~~~~
  17
  18 where the `MTi` are the mangled versions of the `Ti`.
  19 Mangling of types is described in the Mangling Types section below.
  20 Note that `T1` appears twice, once not mangled (`T1`) and once mangled
  21 (`MT1`).  The `__` is two consecutive underscores: `_` followed by
  22 `_`.
  23
  24 As a not-so-special case, if `foo` has no arguments, then the mangled method
  25 will have four consecutive underscores:
  26
  27 ~~~~~~~~ {.java}
  28   `T1 foo()`[[br]]
  29 ~~~~~~~~
  30
  31 goes to
  32
  33 ~~~~~~~~ {.java}
  34   `public static T1 foo____MT1(...)`
  35 ~~~~~~~~
  36
  37 If `T1` is not a primitive type, then the mangled `MJI` method looks like
  38
  39 ~~~~~~~~ {.java}
  40   `public static int foo__MT2MT3...__MT1`
  41 ~~~~~~~~
  42
  43 where the `MTi` are as above.  Note that `T1` only appears once in this
  44 case.  The method's return type is `int`.  As before, a method with no
  45 arguments gets mangled to something with four consecutive underscores.
  46
  47 Also, the use of generics is ignored when mangling names.
  48
  49
  50 ## Mangling Constructors ##
  51 Constructors are treated as methods named `$init` with return type `void`.
  52
  53
  54 ## Mangling Static Initializers ##
  55 Static initializers are treated as methods named `$clinit` with no
  56 arguments and return type `void`.  Thus, their MJI versions always
  57 have the mangled signature:
  58
  59 ~~~~~~~~ {.java}
  60 public static void $clinit____V (MJIEnv env, int clsObjRef)
  61 ~~~~~~~~
  62
  63 or the equivalent unmangled signature:
  64
  65 ~~~~~~~~ {.java}
  66 public static void $clinit (MJIEnv env, int clsObjRef)
  67 ~~~~~~~~
  68
  69
  70 ## Mangling Types ##
  71   - Convert primitives and `void` as follows
  72
  73     |Java Type|Mangled Type|
  74     | ------- |:---:|
  75     |`boolean`|`Z`|
  76     |`byte`   |`B`|
  77     |`char`   |`C`|
  78     |`short`  |`S`|
  79     |`int`    |`I`|
  80     |`long`   |`J`|
  81     |`float`  |`F`|
  82     |`double` |`D`|
  83     |`void`   |`V`|
  84
  85   - Convert a non-array reference type `T` in package `x.y`
  86     (e.g. `java.lang.String`) as follows
  87     - `x.y.T`   --> `Lx_y_T_2`
  88     - Example: `java.lang.String` --> `Ljava_lang_String_2`
  89
  90   - Convert an array of primitive type `T`
  91     (e.g. `byte[]`) as follows:
  92     - `T[]` --> `_3MT`  where `MT` is the mangled version of `T`
  93       (e.g. for `T=byte`, `MT=B`)
  94     - Example: `byte[]` --> `_3B`
  95
  96   - Convert an array of reference type `T` in package `x.y`
  97     (e.g. `java.lang.String[]`) as follows:
  98     - `x.y.T[]` --> `_3Lx_y_T_2`
  99     - Example: `java.lang.String[]` --> `_3Ljava_lang_String_2`
 100
 101
 102 ## Method Examples ##
 103
 104  `void` return type, single primitive argument:
 105
 106 ~~~~~~~~ {.java}
 107   public static void resetCounter(int id)
 108 -->
 109   public static final void resetCounter__I__V(MJIEnv env, int objref, int id)
 110 ~~~~~~~~
 111
 112  Primitive return type, no arguments:
 113
 114 ~~~~~~~~ {.java}
 115   public native boolean isArray()
 116 -->
 117   public static boolean isArray____Z(MJIEnv env, int objref)
 118 ~~~~~~~~
 119
 120  Primitive return type, single primitive argument:
 121
 122 ~~~~~~~~ {.java}
 123   public static double abs(double a)
 124 -->
 125   public static double abs__D__D(MJIEnv env, int clsObjRef, double a)
 126 ~~~~~~~~
 127
 128  Primitive return type, two primitive arguments:
 129
 130 ~~~~~~~~ {.java}
 131   public static long min(long a, long b)
 132 -->
 133   public static long min__JJ__J(MJIEnv env, int clsObjRef, long a, long b)
 134 ~~~~~~~~
 135
 136
 137  `void` return type, arguments include an array of a primitive type:
 138
 139 ~~~~~~~~ {.java}
 140   public native void write (byte[] buf, int off, int len);
 141 -->
 142   public static void write___3BII__V(MJIEnv env, int objref,
 143                                      int bufRef, int off, int len)
 144 ~~~~~~~~
 145
 146
 147  `void` return type, argument is an array of a reference type:
 148
 149 ~~~~~~~~ {.java}
 150    public static void print(String s)
 151 -->
 152   public static void print___3Ljava_lang_String_2__V(MJIEnv env, int clsRef, int argsRef)
 153 ~~~~~~~~
 154
 155  Array of reference types returned, no arguments:
 156
 157 ~~~~~~~~ {.java}
 158   public native Annotation[] getAnnotations()
 159 -->
 160   public static int getAnnotations_____3Ljava_lang_annotation_Annotation_2(MJIEnv env, int robj)
 161 ~~~~~~~~
 162    Notice there are 5 underscores before the `3L`: two marking the
 163    arguments, two marking the return type, and one from the `_3`
 164    signalling an array.
 165
 166  Array of reference types using generics returned, no arguments:
 167
 168 ~~~~~~~~ {.java}
 169   public native Class<?>[] getParameterTypes()
 170 -->
 171   public static int getParameterTypes_____3Ljava_lang_Class_2(MJIEnv env, int objref)
 172 ~~~~~~~~
 173
 174 Note: the use of generics is ignored in the mangling.
 175
 176
 177
 178 ## Constructor Examples ##
 179
 180 Constructors are treated as though they were methods named `$init`
 181 returning `void`, so the method examples above should also be helpful
 182 for constructors.  Here are a few more examples.
 183
 184 In the class `ConsoleOutputStream`:
 185
 186 ~~~~~~~~ {.java}
 187   public ConsoleOutputStream()
 188 -->
 189   public static void $init____V(MJIEnv env, int objref)
 190 ~~~~~~~~
 191
 192 In the class `AtomicLongFieldUpdater`:
 193
 194 ~~~~~~~~ {.java}
 195   protected AtomicLongFieldUpdater(Class<T> objClass, String fieldName)
 196 -->
 197   public static void $init__Ljava_lang_Class_2Ljava_lang_String_2__V
 198                          (MJIEnv env, int objRef,
 199                           int tClsObjRef, int fNameRef)
 200 ~~~~~~~~