Blame - android-35/java/lang/invoke/MethodHandles.java - platform/prebuilts/fullsdk/sources

private static List<Class<?>> buildCommonSuffix(List<MethodHandle> init, List<MethodHandle> step, List<MethodHandle> pred, List<MethodHandle> fini, int cpSize) {

4616

final List<Class<?>> longest1 = longestParameterList(Stream.of(step, pred, fini).flatMap(List::stream), cpSize);

4617

final List<Class<?>> longest2 = longestParameterList(init.stream(), 0);

4618

return longestParameterList(Arrays.asList(longest1, longest2));

4619

}

4620

4621

private static void loopChecks1b(List<MethodHandle> init, List<Class<?>> commonSuffix) {

4622

if (init.stream().filter(Objects::nonNull).map(MethodHandle::type).

4623

anyMatch(t -> !t.effectivelyIdenticalParameters(0, commonSuffix))) {

4624

throw newIllegalArgumentException("found non-effectively identical init parameter type lists: " + init +

4625

" (common suffix: " + commonSuffix + ")");

}

}

private static void loopChecks1cd(List<MethodHandle> pred, List<MethodHandle> fini, Class<?> loopReturnType) {

4630

if (fini.stream().filter(Objects::nonNull).map(MethodHandle::type).map(MethodType::returnType).

4631

anyMatch(t -> t != loopReturnType)) {

4632

throw newIllegalArgumentException("found non-identical finalizer return types: " + fini + " (return type: " +

4633

loopReturnType + ")");

4634

}

4635

4636

if (!pred.stream().filter(Objects::nonNull).findFirst().isPresent()) {

4637

throw newIllegalArgumentException("no predicate found", pred);

4638

}

4639

if (pred.stream().filter(Objects::nonNull).map(MethodHandle::type).map(MethodType::returnType).

4640

anyMatch(t -> t != boolean.class)) {

4641

throw newIllegalArgumentException("predicates must have boolean return type", pred);

}

}

private static void loopChecks2(List<MethodHandle> step, List<MethodHandle> pred, List<MethodHandle> fini, List<Class<?>> commonParameterSequence) {

4646

if (Stream.of(step, pred, fini).flatMap(List::stream).filter(Objects::nonNull).map(MethodHandle::type).

4647

anyMatch(t -> !t.effectivelyIdenticalParameters(0, commonParameterSequence))) {

4648

throw newIllegalArgumentException("found non-effectively identical parameter type lists:\nstep: " + step +

4649

"\npred: " + pred + "\nfini: " + fini + " (common parameter sequence: " + commonParameterSequence + ")");

}

}

private static List<MethodHandle> fillParameterTypes(List<MethodHandle> hs, final List<Class<?>> targetParams) {

4654

return hs.stream().map(h -> {

4655

int pc = h.type().parameterCount();

4656

int tpsize = targetParams.size();

4657

return pc < tpsize ? dropArguments0(h, pc, targetParams.subList(pc, tpsize)) : h;

4658

}).collect(Collectors.toList());

4659

}

4660

4661

private static List<MethodHandle> fixArities(List<MethodHandle> hs) {

4662

return hs.stream().map(MethodHandle::asFixedArity).collect(Collectors.toList());

}

/**

* Constructs a {@code while} loop from an initializer, a body, and a predicate.

4667

* This is a convenience wrapper for the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.

4668

*

4669

* The {@code pred} handle describes the loop condition; and {@code body}, its body. The loop resulting from this

4670

* method will, in each iteration, first evaluate the predicate and then execute its body (if the predicate

4671

* evaluates to {@code true}).

4672

* The loop will terminate once the predicate evaluates to {@code false} (the body will not be executed in this case).

4673

*

4674

* The {@code init} handle describes the initial value of an additional optional loop-local variable.

4675

* In each iteration, this loop-local variable, if present, will be passed to the {@code body}

4676

* and updated with the value returned from its invocation. The result of loop execution will be

4677

* the final value of the additional loop-local variable (if present).

4678

*

4679

* The following rules hold for these argument handles:<ul>

4680

* <li>The {@code body} handle must not be {@code null}; its type must be of the form

4681

* {@code (V A...)V}, where {@code V} is non-{@code void}, or else {@code (A...)void}.

4682

* (In the {@code void} case, we assign the type {@code void} to the name {@code V},

4683

* and we will write {@code (V A...)V} with the understanding that a {@code void} type {@code V}

4684

* is quietly dropped from the parameter list, leaving {@code (A...)V}.)

4685

* <li>The parameter list {@code (V A...)} of the body is called the internal parameter list.

4686

* It will constrain the parameter lists of the other loop parts.

4687

* <li>If the iteration variable type {@code V} is dropped from the internal parameter list, the resulting shorter

4688

* list {@code (A...)} is called the external parameter list.

4689

* <li>The body return type {@code V}, if non-{@code void}, determines the type of an

4690

* additional state variable of the loop.

4691

* The body must both accept and return a value of this type {@code V}.

4692

* <li>If {@code init} is non-{@code null}, it must have return type {@code V}.

4693

* Its parameter list (of some <a href="MethodHandles.html#astar">form {@code (A*)}</a>) must be

4694

* <a href="MethodHandles.html#effid">effectively identical</a>

4695

* to the external parameter list {@code (A...)}.

4696

* <li>If {@code init} is {@code null}, the loop variable will be initialized to its

4697

* {@linkplain #empty default value}.

4698

* <li>The {@code pred} handle must not be {@code null}. It must have {@code boolean} as its return type.

4699

* Its parameter list (either empty or of the form {@code (V A*)}) must be

4700

* effectively identical to the internal parameter list.

4701

* </ul>

4702

*

4703

* The resulting loop handle's result type and parameter signature are determined as follows:<ul>

4704

* <li>The loop handle's result type is the result type {@code V} of the body.

4705

* <li>The loop handle's parameter types are the types {@code (A...)},

4706

* from the external parameter list.

4707

* </ul>

4708

*

4709

* Here is pseudocode for the resulting loop handle. In the code, {@code V}/{@code v} represent the type / value of

4710

* the sole loop variable as well as the result type of the loop; and {@code A}/{@code a}, that of the argument

4711

* passed to the loop.

4712

* <blockquote><pre>{@code

4713

* V init(A...);

4714

* boolean pred(V, A...);

4715

* V body(V, A...);

4716

* V whileLoop(A... a...) {

4717

* V v = init(a...);

4718

* while (pred(v, a...)) {

* v = body(v, a...);

* }

* return v;

* }

* }</pre></blockquote>

4724

*

4725

* @apiNote Example:

4726

* <blockquote><pre>{@code

4727

* // implement the zip function for lists as a loop handle

4728

* static List<String> initZip(Iterator<String> a, Iterator<String> b) { return new ArrayList<>(); }

4729

* static boolean zipPred(List<String> zip, Iterator<String> a, Iterator<String> b) { return a.hasNext() && b.hasNext(); }

4730

* static List<String> zipStep(List<String> zip, Iterator<String> a, Iterator<String> b) {

* zip.add(a.next());

* zip.add(b.next());

* return zip;

* }

* // assume MH_initZip, MH_zipPred, and MH_zipStep are handles to the above methods

4736

* MethodHandle loop = MethodHandles.whileLoop(MH_initZip, MH_zipPred, MH_zipStep);

4737

* List<String> a = Arrays.asList("a", "b", "c", "d");

4738

* List<String> b = Arrays.asList("e", "f", "g", "h");

4739

* List<String> zipped = Arrays.asList("a", "e", "b", "f", "c", "g", "d", "h");

4740

* assertEquals(zipped, (List<String>) loop.invoke(a.iterator(), b.iterator()));

4741

* }</pre></blockquote>

4742

*

4743

*

4744

* @apiNote The implementation of this method can be expressed as follows:

4745

* <blockquote><pre>{@code

4746

* MethodHandle whileLoop(MethodHandle init, MethodHandle pred, MethodHandle body) {

4747

* MethodHandle fini = (body.type().returnType() == void.class

4748

* ? null : identity(body.type().returnType()));

4749

* MethodHandle[]

4750

* checkExit = { null, null, pred, fini },

4751

* varBody = { init, body };

4752

* return loop(checkExit, varBody);

4753

* }

4754

* }</pre></blockquote>

4755

*

4756

* @param init optional initializer, providing the initial value of the loop variable.

4757

* May be {@code null}, implying a default initial value. See above for other constraints.

4758

* @param pred condition for the loop, which may not be {@code null}. Its result type must be {@code boolean}. See

4759

* above for other constraints.

4760

* @param body body of the loop, which may not be {@code null}. It controls the loop parameters and result type.

4761

* See above for other constraints.

4762

*

4763

* @return a method handle implementing the {@code while} loop as described by the arguments.

4764

* @throws IllegalArgumentException if the rules for the arguments are violated.

4765

* @throws NullPointerException if {@code pred} or {@code body} are {@code null}.

4766

*

4767

* @see #loop(MethodHandle[][])

4768

* @see #doWhileLoop(MethodHandle, MethodHandle, MethodHandle)

4769

* @since 9

4770

*/

4771

public static MethodHandle whileLoop(MethodHandle init, MethodHandle pred, MethodHandle body) {

4772

whileLoopChecks(init, pred, body);

4773

MethodHandle fini = identityOrVoid(body.type().returnType());

4774

MethodHandle[] checkExit = { null, null, pred, fini };

4775

MethodHandle[] varBody = { init, body };

4776

return loop(checkExit, varBody);

}

/**

* Constructs a {@code do-while} loop from an initializer, a body, and a predicate.

4781

* This is a convenience wrapper for the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.

4782

*

4783

* The {@code pred} handle describes the loop condition; and {@code body}, its body. The loop resulting from this

4784

* method will, in each iteration, first execute its body and then evaluate the predicate.

4785

* The loop will terminate once the predicate evaluates to {@code false} after an execution of the body.

4786

*

4787

* The {@code init} handle describes the initial value of an additional optional loop-local variable.

4788

* In each iteration, this loop-local variable, if present, will be passed to the {@code body}

4789

* and updated with the value returned from its invocation. The result of loop execution will be

4790

* the final value of the additional loop-local variable (if present).

4791

*

4792

* The following rules hold for these argument handles:<ul>

4793

* <li>The {@code body} handle must not be {@code null}; its type must be of the form

4794

* {@code (V A...)V}, where {@code V} is non-{@code void}, or else {@code (A...)void}.

4795

* (In the {@code void} case, we assign the type {@code void} to the name {@code V},

4796

* and we will write {@code (V A...)V} with the understanding that a {@code void} type {@code V}

4797

* is quietly dropped from the parameter list, leaving {@code (A...)V}.)

4798

* <li>The parameter list {@code (V A...)} of the body is called the internal parameter list.

4799

* It will constrain the parameter lists of the other loop parts.

4800

* <li>If the iteration variable type {@code V} is dropped from the internal parameter list, the resulting shorter

4801

* list {@code (A...)} is called the external parameter list.

4802

* <li>The body return type {@code V}, if non-{@code void}, determines the type of an

4803

* additional state variable of the loop.

4804

* The body must both accept and return a value of this type {@code V}.

4805

* <li>If {@code init} is non-{@code null}, it must have return type {@code V}.

4806

* Its parameter list (of some <a href="MethodHandles.html#astar">form {@code (A*)}</a>) must be

4807

* <a href="MethodHandles.html#effid">effectively identical</a>

4808

* to the external parameter list {@code (A...)}.

4809

* <li>If {@code init} is {@code null}, the loop variable will be initialized to its

4810

* {@linkplain #empty default value}.

4811

* <li>The {@code pred} handle must not be {@code null}. It must have {@code boolean} as its return type.

4812

* Its parameter list (either empty or of the form {@code (V A*)}) must be

4813

* effectively identical to the internal parameter list.

4814

* </ul>

4815

*

4816

* The resulting loop handle's result type and parameter signature are determined as follows:<ul>

4817

* <li>The loop handle's result type is the result type {@code V} of the body.

4818

* <li>The loop handle's parameter types are the types {@code (A...)},

4819

* from the external parameter list.

4820

* </ul>

4821

*

4822

* Here is pseudocode for the resulting loop handle. In the code, {@code V}/{@code v} represent the type / value of

4823

* the sole loop variable as well as the result type of the loop; and {@code A}/{@code a}, that of the argument

4824

* passed to the loop.

4825

* <blockquote><pre>{@code

4826

* V init(A...);

4827

* boolean pred(V, A...);

4828

* V body(V, A...);

4829

* V doWhileLoop(A... a...) {

* V v = init(a...);

* do {

* v = body(v, a...);

* } while (pred(v, a...));

4834

* return v;

4835

* }

4836

* }</pre></blockquote>

4837

*

4838

* @apiNote Example:

4839

* <blockquote><pre>{@code

4840

* // int i = 0; while (i < limit) { ++i; } return i; => limit

4841

* static int zero(int limit) { return 0; }

4842

* static int step(int i, int limit) { return i + 1; }

4843

* static boolean pred(int i, int limit) { return i < limit; }

4844

* // assume MH_zero, MH_step, and MH_pred are handles to the above methods

4845

* MethodHandle loop = MethodHandles.doWhileLoop(MH_zero, MH_step, MH_pred);

4846

* assertEquals(23, loop.invoke(23));

4847

* }</pre></blockquote>

4848

*

4849

*

4850

* @apiNote The implementation of this method can be expressed as follows:

4851

* <blockquote><pre>{@code

4852

* MethodHandle doWhileLoop(MethodHandle init, MethodHandle body, MethodHandle pred) {

4853

* MethodHandle fini = (body.type().returnType() == void.class

4854

* ? null : identity(body.type().returnType()));

4855

* MethodHandle[] clause = { init, body, pred, fini };

4856

* return loop(clause);

4857

* }

4858

* }</pre></blockquote>

4859

*

4860

* @param init optional initializer, providing the initial value of the loop variable.

4861

* May be {@code null}, implying a default initial value. See above for other constraints.

4862

* @param body body of the loop, which may not be {@code null}. It controls the loop parameters and result type.

4863

* See above for other constraints.

4864

* @param pred condition for the loop, which may not be {@code null}. Its result type must be {@code boolean}. See

4865

* above for other constraints.

4866

*

4867

* @return a method handle implementing the {@code while} loop as described by the arguments.

4868

* @throws IllegalArgumentException if the rules for the arguments are violated.

4869

* @throws NullPointerException if {@code pred} or {@code body} are {@code null}.

4870

*

4871

* @see #loop(MethodHandle[][])

4872

* @see #whileLoop(MethodHandle, MethodHandle, MethodHandle)

4873

* @since 9

4874

*/

4875

public static MethodHandle doWhileLoop(MethodHandle init, MethodHandle body, MethodHandle pred) {

4876

whileLoopChecks(init, pred, body);

4877

MethodHandle fini = identityOrVoid(body.type().returnType());

4878

MethodHandle[] clause = {init, body, pred, fini };

return loop(clause);

}

private static void whileLoopChecks(MethodHandle init, MethodHandle pred, MethodHandle body) {

4883

Objects.requireNonNull(pred);

4884

Objects.requireNonNull(body);

4885

MethodType bodyType = body.type();

4886

Class<?> returnType = bodyType.returnType();

4887

List<Class<?>> innerList = bodyType.parameterList();

4888

List<Class<?>> outerList = innerList;

4889

if (returnType == void.class) {

4890

// OK

4891

} else if (innerList.size() == 0 || innerList.get(0) != returnType) {

4892

// leading V argument missing => error

4893

MethodType expected = bodyType.insertParameterTypes(0, returnType);

4894

throw misMatchedTypes("body function", bodyType, expected);

4895

} else {

4896

outerList = innerList.subList(1, innerList.size());

4897

}

4898

MethodType predType = pred.type();

4899

if (predType.returnType() != boolean.class ||

4900

!predType.effectivelyIdenticalParameters(0, innerList)) {

4901

throw misMatchedTypes("loop predicate", predType, methodType(boolean.class, innerList));

4902

}

4903

if (init != null) {

4904

MethodType initType = init.type();

4905

if (initType.returnType() != returnType ||

4906

!initType.effectivelyIdenticalParameters(0, outerList)) {

4907

throw misMatchedTypes("loop initializer", initType, methodType(returnType, outerList));

}

}

}

/**

* Constructs a loop that runs a given number of iterations.

4914

* This is a convenience wrapper for the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.

4915

*

4916

* The number of iterations is determined by the {@code iterations} handle evaluation result.

4917

* The loop counter {@code i} is an extra loop iteration variable of type {@code int}.

4918

* It will be initialized to 0 and incremented by 1 in each iteration.

4919

*

4920

* If the {@code body} handle returns a non-{@code void} type {@code V}, a leading loop iteration variable

4921

* of that type is also present. This variable is initialized using the optional {@code init} handle,

4922

* or to the {@linkplain #empty default value} of type {@code V} if that handle is {@code null}.

4923

*

4924

* In each iteration, the iteration variables are passed to an invocation of the {@code body} handle.

4925

* A non-{@code void} value returned from the body (of type {@code V}) updates the leading

4926

* iteration variable.

4927

* The result of the loop handle execution will be the final {@code V} value of that variable

4928

* (or {@code void} if there is no {@code V} variable).

4929

*

4930

* The following rules hold for the argument handles:<ul>

4931

* <li>The {@code iterations} handle must not be {@code null}, and must return

4932

* the type {@code int}, referred to here as {@code I} in parameter type lists.

4933

* <li>The {@code body} handle must not be {@code null}; its type must be of the form

4934

* {@code (V I A...)V}, where {@code V} is non-{@code void}, or else {@code (I A...)void}.

4935

* (In the {@code void} case, we assign the type {@code void} to the name {@code V},

4936

* and we will write {@code (V I A...)V} with the understanding that a {@code void} type {@code V}

4937

* is quietly dropped from the parameter list, leaving {@code (I A...)V}.)

4938

* <li>The parameter list {@code (V I A...)} of the body contributes to a list

4939

* of types called the internal parameter list.

4940

* It will constrain the parameter lists of the other loop parts.

4941

* <li>As a special case, if the body contributes only {@code V} and {@code I} types,

4942

* with no additional {@code A} types, then the internal parameter list is extended by

4943

* the argument types {@code A...} of the {@code iterations} handle.

4944

* <li>If the iteration variable types {@code (V I)} are dropped from the internal parameter list, the resulting shorter

4945

* list {@code (A...)} is called the external parameter list.

4946

* <li>The body return type {@code V}, if non-{@code void}, determines the type of an

4947

* additional state variable of the loop.

4948

* The body must both accept a leading parameter and return a value of this type {@code V}.

4949

* <li>If {@code init} is non-{@code null}, it must have return type {@code V}.

4950

* Its parameter list (of some <a href="MethodHandles.html#astar">form {@code (A*)}</a>) must be

4951

* <a href="MethodHandles.html#effid">effectively identical</a>

4952

* to the external parameter list {@code (A...)}.

4953

* <li>If {@code init} is {@code null}, the loop variable will be initialized to its

4954

* {@linkplain #empty default value}.

4955

* <li>The parameter list of {@code iterations} (of some form {@code (A*)}) must be

4956

* effectively identical to the external parameter list {@code (A...)}.

4957

* </ul>

4958

*

4959

* The resulting loop handle's result type and parameter signature are determined as follows:<ul>

4960

* <li>The loop handle's result type is the result type {@code V} of the body.

4961

* <li>The loop handle's parameter types are the types {@code (A...)},

4962

* from the external parameter list.

4963

* </ul>

4964

*

4965

* Here is pseudocode for the resulting loop handle. In the code, {@code V}/{@code v} represent the type / value of

4966

* the second loop variable as well as the result type of the loop; and {@code A...}/{@code a...} represent

4967

* arguments passed to the loop.

4968

* <blockquote><pre>{@code

4969

* int iterations(A...);

4970

* V init(A...);

4971

* V body(V, int, A...);

4972

* V countedLoop(A... a...) {

4973

* int end = iterations(a...);

4974

* V v = init(a...);

4975

* for (int i = 0; i < end; ++i) {

4976

* v = body(v, i, a...);

* }

* return v;

* }

* }</pre></blockquote>

4981

*

4982

* @apiNote Example with a fully conformant body method:

4983

* <blockquote><pre>{@code

4984

* // String s = "Lambdaman!"; for (int i = 0; i < 13; ++i) { s = "na " + s; } return s;

4985

* // => a variation on a well known theme

4986

* static String step(String v, int counter, String init) { return "na " + v; }

4987

* // assume MH_step is a handle to the method above

4988

* MethodHandle fit13 = MethodHandles.constant(int.class, 13);

4989

* MethodHandle start = MethodHandles.identity(String.class);

4990

* MethodHandle loop = MethodHandles.countedLoop(fit13, start, MH_step);

4991

* assertEquals("na na na na na na na na na na na na na Lambdaman!", loop.invoke("Lambdaman!"));

4992

* }</pre></blockquote>

4993

*

4994

* @apiNote Example with the simplest possible body method type,

4995

* and passing the number of iterations to the loop invocation:

4996

* <blockquote><pre>{@code

4997

* // String s = "Lambdaman!"; for (int i = 0; i < 13; ++i) { s = "na " + s; } return s;

4998

* // => a variation on a well known theme

4999

* static String step(String v, int counter ) { return "na " + v; }

5000

* // assume MH_step is a handle to the method above

5001

* MethodHandle count = MethodHandles.dropArguments(MethodHandles.identity(int.class), 1, String.class);

5002

* MethodHandle start = MethodHandles.dropArguments(MethodHandles.identity(String.class), 0, int.class);

5003

* MethodHandle loop = MethodHandles.countedLoop(count, start, MH_step); // (v, i) -> "na " + v

5004

* assertEquals("na na na na na na na na na na na na na Lambdaman!", loop.invoke(13, "Lambdaman!"));

5005

* }</pre></blockquote>

5006

*

5007

* @apiNote Example that treats the number of iterations, string to append to, and string to append

5008

* as loop parameters:

5009

* <blockquote><pre>{@code

5010

* // String s = "Lambdaman!", t = "na"; for (int i = 0; i < 13; ++i) { s = t + " " + s; } return s;

5011

* // => a variation on a well known theme

5012

* static String step(String v, int counter, int iterations_, String pre, String start_) { return pre + " " + v; }

5013

* // assume MH_step is a handle to the method above

5014

* MethodHandle count = MethodHandles.identity(int.class);

5015

* MethodHandle start = MethodHandles.dropArguments(MethodHandles.identity(String.class), 0, int.class, String.class);

5016

* MethodHandle loop = MethodHandles.countedLoop(count, start, MH_step); // (v, i, _, pre, _) -> pre + " " + v

5017

* assertEquals("na na na na na na na na na na na na na Lambdaman!", loop.invoke(13, "na", "Lambdaman!"));

5018

* }</pre></blockquote>

5019

*

5020

* @apiNote Example that illustrates the usage of {@link #dropArgumentsToMatch(MethodHandle, int, List, int)}

5021

* to enforce a loop type:

5022

* <blockquote><pre>{@code

5023

* // String s = "Lambdaman!", t = "na"; for (int i = 0; i < 13; ++i) { s = t + " " + s; } return s;

5024

* // => a variation on a well known theme

5025

* static String step(String v, int counter, String pre) { return pre + " " + v; }

5026

* // assume MH_step is a handle to the method above

5027

* MethodType loopType = methodType(String.class, String.class, int.class, String.class);

5028

* MethodHandle count = MethodHandles.dropArgumentsToMatch(MethodHandles.identity(int.class), 0, loopType.parameterList(), 1);

5029

* MethodHandle start = MethodHandles.dropArgumentsToMatch(MethodHandles.identity(String.class), 0, loopType.parameterList(), 2);

5030

* MethodHandle body = MethodHandles.dropArgumentsToMatch(MH_step, 2, loopType.parameterList(), 0);

5031

* MethodHandle loop = MethodHandles.countedLoop(count, start, body); // (v, i, pre, _, _) -> pre + " " + v

5032

* assertEquals("na na na na na na na na na na na na na Lambdaman!", loop.invoke("na", 13, "Lambdaman!"));

5033

* }</pre></blockquote>

5034

*

5035

* @apiNote The implementation of this method can be expressed as follows:

5036

* <blockquote><pre>{@code

5037

* MethodHandle countedLoop(MethodHandle iterations, MethodHandle init, MethodHandle body) {

5038

* return countedLoop(empty(iterations.type()), iterations, init, body);

5039

* }

5040

* }</pre></blockquote>

5041

*

5042

* @param iterations a non-{@code null} handle to return the number of iterations this loop should run. The handle's

5043

* result type must be {@code int}. See above for other constraints.

5044

* @param init optional initializer, providing the initial value of the loop variable.

5045

* May be {@code null}, implying a default initial value. See above for other constraints.

5046

* @param body body of the loop, which may not be {@code null}.

5047

* It controls the loop parameters and result type in the standard case (see above for details).

5048

* It must accept its own return type (if non-void) plus an {@code int} parameter (for the counter),

5049

* and may accept any number of additional types.

5050

* See above for other constraints.

5051

*

5052

* @return a method handle representing the loop.

5053

* @throws NullPointerException if either of the {@code iterations} or {@code body} handles is {@code null}.

5054

* @throws IllegalArgumentException if any argument violates the rules formulated above.

5055

*

5056

* @see #countedLoop(MethodHandle, MethodHandle, MethodHandle, MethodHandle)

5057

* @since 9

5058

*/

5059

public static MethodHandle countedLoop(MethodHandle iterations, MethodHandle init, MethodHandle body) {

5060

return countedLoop(empty(iterations.type()), iterations, init, body);

}

/**

* Constructs a loop that counts over a range of numbers.

5065

* This is a convenience wrapper for the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.

5066

*

5067

* The loop counter {@code i} is a loop iteration variable of type {@code int}.

5068

* The {@code start} and {@code end} handles determine the start (inclusive) and end (exclusive)

5069

* values of the loop counter.

5070

* The loop counter will be initialized to the {@code int} value returned from the evaluation of the

5071

* {@code start} handle and run to the value returned from {@code end} (exclusively) with a step width of 1.

5072

*

5073

* If the {@code body} handle returns a non-{@code void} type {@code V}, a leading loop iteration variable

5074

* of that type is also present. This variable is initialized using the optional {@code init} handle,

5075

* or to the {@linkplain #empty default value} of type {@code V} if that handle is {@code null}.

5076

*

5077

* In each iteration, the iteration variables are passed to an invocation of the {@code body} handle.

5078

* A non-{@code void} value returned from the body (of type {@code V}) updates the leading

5079

* iteration variable.

5080

* The result of the loop handle execution will be the final {@code V} value of that variable

5081

* (or {@code void} if there is no {@code V} variable).

5082

*

5083

* The following rules hold for the argument handles:<ul>

5084

* <li>The {@code start} and {@code end} handles must not be {@code null}, and must both return

5085

* the common type {@code int}, referred to here as {@code I} in parameter type lists.

5086

* <li>The {@code body} handle must not be {@code null}; its type must be of the form

5087

* {@code (V I A...)V}, where {@code V} is non-{@code void}, or else {@code (I A...)void}.

5088

* (In the {@code void} case, we assign the type {@code void} to the name {@code V},

5089

* and we will write {@code (V I A...)V} with the understanding that a {@code void} type {@code V}

5090

* is quietly dropped from the parameter list, leaving {@code (I A...)V}.)

5091

* <li>The parameter list {@code (V I A...)} of the body contributes to a list

5092

* of types called the internal parameter list.

5093

* It will constrain the parameter lists of the other loop parts.

5094

* <li>As a special case, if the body contributes only {@code V} and {@code I} types,

5095

* with no additional {@code A} types, then the internal parameter list is extended by

5096

* the argument types {@code A...} of the {@code end} handle.

5097

* <li>If the iteration variable types {@code (V I)} are dropped from the internal parameter list, the resulting shorter

5098

* list {@code (A...)} is called the external parameter list.

5099

* <li>The body return type {@code V}, if non-{@code void}, determines the type of an

5100

* additional state variable of the loop.

5101

* The body must both accept a leading parameter and return a value of this type {@code V}.

5102

* <li>If {@code init} is non-{@code null}, it must have return type {@code V}.

5103

* Its parameter list (of some <a href="MethodHandles.html#astar">form {@code (A*)}</a>) must be

5104

* <a href="MethodHandles.html#effid">effectively identical</a>

5105

* to the external parameter list {@code (A...)}.

5106

* <li>If {@code init} is {@code null}, the loop variable will be initialized to its

5107

* {@linkplain #empty default value}.

5108

* <li>The parameter list of {@code start} (of some form {@code (A*)}) must be

5109

* effectively identical to the external parameter list {@code (A...)}.

5110

* <li>Likewise, the parameter list of {@code end} must be effectively identical

5111

* to the external parameter list.

5112

* </ul>

5113

*

5114

* The resulting loop handle's result type and parameter signature are determined as follows:<ul>

5115

* <li>The loop handle's result type is the result type {@code V} of the body.

5116

* <li>The loop handle's parameter types are the types {@code (A...)},

5117

* from the external parameter list.

5118

* </ul>

5119

*

5120

* Here is pseudocode for the resulting loop handle. In the code, {@code V}/{@code v} represent the type / value of

5121

* the second loop variable as well as the result type of the loop; and {@code A...}/{@code a...} represent

5122

* arguments passed to the loop.

5123

* <blockquote><pre>{@code

* int start(A...);

* int end(A...);

* V init(A...);

* V body(V, int, A...);

5128

* V countedLoop(A... a...) {

5129

* int e = end(a...);

5130

* int s = start(a...);

5131

* V v = init(a...);

5132

* for (int i = s; i < e; ++i) {

5133

* v = body(v, i, a...);

* }

* return v;

* }

* }</pre></blockquote>

5138

*

5139

* @apiNote The implementation of this method can be expressed as follows:

5140

* <blockquote><pre>{@code

5141

* MethodHandle countedLoop(MethodHandle start, MethodHandle end, MethodHandle init, MethodHandle body) {

5142

* MethodHandle returnVar = dropArguments(identity(init.type().returnType()), 0, int.class, int.class);

5143

* // assume MH_increment and MH_predicate are handles to implementation-internal methods with

5144

* // the following semantics:

5145

* // MH_increment: (int limit, int counter) -> counter + 1

5146

* // MH_predicate: (int limit, int counter) -> counter < limit

5147

* Class<?> counterType = start.type().returnType(); // int

5148

* Class<?> returnType = body.type().returnType();

5149

* MethodHandle incr = MH_increment, pred = MH_predicate, retv = null;

5150

* if (returnType != void.class) { // ignore the V variable

5151

* incr = dropArguments(incr, 1, returnType); // (limit, v, i) => (limit, i)

5152

* pred = dropArguments(pred, 1, returnType); // ditto

5153

* retv = dropArguments(identity(returnType), 0, counterType); // ignore limit

5154

* }

5155

* body = dropArguments(body, 0, counterType); // ignore the limit variable

5156

* MethodHandle[]

5157

* loopLimit = { end, null, pred, retv }, // limit = end(); i < limit || return v

5158

* bodyClause = { init, body }, // v = init(); v = body(v, i)

5159

* indexVar = { start, incr }; // i = start(); i = i + 1

5160

* return loop(loopLimit, bodyClause, indexVar);

5161

* }

5162

* }</pre></blockquote>

5163

*

5164

* @param start a non-{@code null} handle to return the start value of the loop counter, which must be {@code int}.

5165

* See above for other constraints.

5166

* @param end a non-{@code null} handle to return the end value of the loop counter (the loop will run to

5167

* {@code end-1}). The result type must be {@code int}. See above for other constraints.

5168

* @param init optional initializer, providing the initial value of the loop variable.

5169

* May be {@code null}, implying a default initial value. See above for other constraints.

5170

* @param body body of the loop, which may not be {@code null}.

5171

* It controls the loop parameters and result type in the standard case (see above for details).

5172

* It must accept its own return type (if non-void) plus an {@code int} parameter (for the counter),

5173

* and may accept any number of additional types.

5174

* See above for other constraints.

5175

*

5176

* @return a method handle representing the loop.

5177

* @throws NullPointerException if any of the {@code start}, {@code end}, or {@code body} handles is {@code null}.

5178

* @throws IllegalArgumentException if any argument violates the rules formulated above.

5179

*

5180

* @see #countedLoop(MethodHandle, MethodHandle, MethodHandle)

5181

* @since 9

5182

*/

5183

public static MethodHandle countedLoop(MethodHandle start, MethodHandle end, MethodHandle init, MethodHandle body) {

5184

countedLoopChecks(start, end, init, body);

5185

Class<?> counterType = start.type().returnType(); // int, but who's counting?

5186

Class<?> limitType = end.type().returnType(); // yes, int again

5187

Class<?> returnType = body.type().returnType();

5188

// Android-changed: getConstantHandle is in MethodHandles.

5189

// MethodHandle incr = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_countedLoopStep);

5190

// MethodHandle pred = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_countedLoopPred);

5191

MethodHandle incr = getConstantHandle(MH_countedLoopStep);

5192

MethodHandle pred = getConstantHandle(MH_countedLoopPred);

5193

MethodHandle retv = null;

5194

if (returnType != void.class) {

5195

incr = dropArguments(incr, 1, returnType); // (limit, v, i) => (limit, i)

5196

pred = dropArguments(pred, 1, returnType); // ditto

5197

retv = dropArguments(identity(returnType), 0, counterType);

5198

}

5199

body = dropArguments(body, 0, counterType); // ignore the limit variable

5200

MethodHandle[]

5201

loopLimit = { end, null, pred, retv }, // limit = end(); i < limit || return v

5202

bodyClause = { init, body }, // v = init(); v = body(v, i)

5203

indexVar = { start, incr }; // i = start(); i = i + 1

5204

return loop(loopLimit, bodyClause, indexVar);

5205

}

5206

5207

private static void countedLoopChecks(MethodHandle start, MethodHandle end, MethodHandle init, MethodHandle body) {

5208

Objects.requireNonNull(start);

5209

Objects.requireNonNull(end);

5210

Objects.requireNonNull(body);

5211

Class<?> counterType = start.type().returnType();

5212

if (counterType != int.class) {

5213

MethodType expected = start.type().changeReturnType(int.class);

5214

throw misMatchedTypes("start function", start.type(), expected);

5215

} else if (end.type().returnType() != counterType) {

5216

MethodType expected = end.type().changeReturnType(counterType);

5217

throw misMatchedTypes("end function", end.type(), expected);

5218

}

5219

MethodType bodyType = body.type();

5220

Class<?> returnType = bodyType.returnType();

5221

List<Class<?>> innerList = bodyType.parameterList();

5222

// strip leading V value if present

5223

int vsize = (returnType == void.class ? 0 : 1);

5224

if (vsize != 0 && (innerList.size() == 0 || innerList.get(0) != returnType)) {

5225

// argument list has no "V" => error

5226

MethodType expected = bodyType.insertParameterTypes(0, returnType);

5227

throw misMatchedTypes("body function", bodyType, expected);

5228

} else if (innerList.size() <= vsize || innerList.get(vsize) != counterType) {

5229

// missing I type => error

5230

MethodType expected = bodyType.insertParameterTypes(vsize, counterType);

5231

throw misMatchedTypes("body function", bodyType, expected);

5232

}

5233

List<Class<?>> outerList = innerList.subList(vsize + 1, innerList.size());

5234

if (outerList.isEmpty()) {

5235

// special case; take lists from end handle

5236

outerList = end.type().parameterList();

5237

innerList = bodyType.insertParameterTypes(vsize + 1, outerList).parameterList();

5238

}

5239

MethodType expected = methodType(counterType, outerList);

5240

if (!start.type().effectivelyIdenticalParameters(0, outerList)) {

5241

throw misMatchedTypes("start parameter types", start.type(), expected);

5242

}

5243

if (end.type() != start.type() &&

5244

!end.type().effectivelyIdenticalParameters(0, outerList)) {

5245

throw misMatchedTypes("end parameter types", end.type(), expected);

5246

}

5247

if (init != null) {

5248

MethodType initType = init.type();

5249

if (initType.returnType() != returnType ||

5250

!initType.effectivelyIdenticalParameters(0, outerList)) {

5251

throw misMatchedTypes("loop initializer", initType, methodType(returnType, outerList));

}

}

}

/**

* Constructs a loop that ranges over the values produced by an {@code Iterator<T>}.

5258

* This is a convenience wrapper for the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.

5259

*

5260

* The iterator itself will be determined by the evaluation of the {@code iterator} handle.

5261

* Each value it produces will be stored in a loop iteration variable of type {@code T}.

5262

*

5263

* If the {@code body} handle returns a non-{@code void} type {@code V}, a leading loop iteration variable

5264

* of that type is also present. This variable is initialized using the optional {@code init} handle,

5265

* or to the {@linkplain #empty default value} of type {@code V} if that handle is {@code null}.

5266

*

5267

* In each iteration, the iteration variables are passed to an invocation of the {@code body} handle.

5268

* A non-{@code void} value returned from the body (of type {@code V}) updates the leading

5269

* iteration variable.

5270

* The result of the loop handle execution will be the final {@code V} value of that variable

5271

* (or {@code void} if there is no {@code V} variable).

5272

*

5273

* The following rules hold for the argument handles:<ul>

5274

* <li>The {@code body} handle must not be {@code null}; its type must be of the form

5275

* {@code (V T A...)V}, where {@code V} is non-{@code void}, or else {@code (T A...)void}.

5276

* (In the {@code void} case, we assign the type {@code void} to the name {@code V},

5277

* and we will write {@code (V T A...)V} with the understanding that a {@code void} type {@code V}

5278

* is quietly dropped from the parameter list, leaving {@code (T A...)V}.)

5279

* <li>The parameter list {@code (V T A...)} of the body contributes to a list

5280

* of types called the internal parameter list.

5281

* It will constrain the parameter lists of the other loop parts.

5282

* <li>As a special case, if the body contributes only {@code V} and {@code T} types,

5283

* with no additional {@code A} types, then the internal parameter list is extended by

5284

* the argument types {@code A...} of the {@code iterator} handle; if it is {@code null} the

5285

* single type {@code Iterable} is added and constitutes the {@code A...} list.

5286

* <li>If the iteration variable types {@code (V T)} are dropped from the internal parameter list, the resulting shorter

5287

* list {@code (A...)} is called the external parameter list.

5288

* <li>The body return type {@code V}, if non-{@code void}, determines the type of an

5289

* additional state variable of the loop.

5290

* The body must both accept a leading parameter and return a value of this type {@code V}.

5291

* <li>If {@code init} is non-{@code null}, it must have return type {@code V}.

5292

* Its parameter list (of some <a href="MethodHandles.html#astar">form {@code (A*)}</a>) must be

5293

* <a href="MethodHandles.html#effid">effectively identical</a>

5294

* to the external parameter list {@code (A...)}.

5295

* <li>If {@code init} is {@code null}, the loop variable will be initialized to its

5296

* {@linkplain #empty default value}.

5297

* <li>If the {@code iterator} handle is non-{@code null}, it must have the return

5298

* type {@code java.util.Iterator} or a subtype thereof.

5299

* The iterator it produces when the loop is executed will be assumed

5300

* to yield values which can be converted to type {@code T}.

5301

* <li>The parameter list of an {@code iterator} that is non-{@code null} (of some form {@code (A*)}) must be

5302

* effectively identical to the external parameter list {@code (A...)}.

5303

* <li>If {@code iterator} is {@code null} it defaults to a method handle which behaves

5304

* like {@link java.lang.Iterable#iterator()}. In that case, the internal parameter list

5305

* {@code (V T A...)} must have at least one {@code A} type, and the default iterator

5306

* handle parameter is adjusted to accept the leading {@code A} type, as if by

5307

* the {@link MethodHandle#asType asType} conversion method.

5308

* The leading {@code A} type must be {@code Iterable} or a subtype thereof.

5309

* This conversion step, done at loop construction time, must not throw a {@code WrongMethodTypeException}.

5310

* </ul>

5311

*

5312

* The type {@code T} may be either a primitive or reference.

5313

* Since type {@code Iterator<T>} is erased in the method handle representation to the raw type {@code Iterator},

5314

* the {@code iteratedLoop} combinator adjusts the leading argument type for {@code body} to {@code Object}

5315

* as if by the {@link MethodHandle#asType asType} conversion method.

5316

* Therefore, if an iterator of the wrong type appears as the loop is executed, runtime exceptions may occur

5317

* as the result of dynamic conversions performed by {@link MethodHandle#asType(MethodType)}.

5318

*

5319

* The resulting loop handle's result type and parameter signature are determined as follows:<ul>

5320

* <li>The loop handle's result type is the result type {@code V} of the body.

5321

* <li>The loop handle's parameter types are the types {@code (A...)},

5322

* from the external parameter list.

5323

* </ul>

5324

*

5325

* Here is pseudocode for the resulting loop handle. In the code, {@code V}/{@code v} represent the type / value of

5326

* the loop variable as well as the result type of the loop; {@code T}/{@code t}, that of the elements of the

5327

* structure the loop iterates over, and {@code A...}/{@code a...} represent arguments passed to the loop.

5328

* <blockquote><pre>{@code

5329

* Iterator<T> iterator(A...); // defaults to Iterable::iterator

5330

* V init(A...);

5331

* V body(V,T,A...);

5332

* V iteratedLoop(A... a...) {

5333

* Iterator<T> it = iterator(a...);

5334

* V v = init(a...);

5335

* while (it.hasNext()) {

5336

* T t = it.next();

5337

* v = body(v, t, a...);

* }

* return v;

* }

* }</pre></blockquote>

5342

*

5343

* @apiNote Example:

5344

* <blockquote><pre>{@code

5345

* // get an iterator from a list

5346

* static List<String> reverseStep(List<String> r, String e) {

* r.add(0, e);

* return r;

* }

* static List<String> newArrayList() { return new ArrayList<>(); }

5351

* // assume MH_reverseStep and MH_newArrayList are handles to the above methods

5352

* MethodHandle loop = MethodHandles.iteratedLoop(null, MH_newArrayList, MH_reverseStep);

5353

* List<String> list = Arrays.asList("a", "b", "c", "d", "e");

5354

* List<String> reversedList = Arrays.asList("e", "d", "c", "b", "a");

5355

* assertEquals(reversedList, (List<String>) loop.invoke(list));

5356

* }</pre></blockquote>

5357

*

5358

* @apiNote The implementation of this method can be expressed approximately as follows:

5359

* <blockquote><pre>{@code

5360

* MethodHandle iteratedLoop(MethodHandle iterator, MethodHandle init, MethodHandle body) {

5361

* // assume MH_next, MH_hasNext, MH_startIter are handles to methods of Iterator/Iterable

5362

* Class<?> returnType = body.type().returnType();

5363

* Class<?> ttype = body.type().parameterType(returnType == void.class ? 0 : 1);

5364

* MethodHandle nextVal = MH_next.asType(MH_next.type().changeReturnType(ttype));

5365

* MethodHandle retv = null, step = body, startIter = iterator;

5366

* if (returnType != void.class) {

5367

* // the simple thing first: in (I V A...), drop the I to get V

5368

* retv = dropArguments(identity(returnType), 0, Iterator.class);

5369

* // body type signature (V T A...), internal loop types (I V A...)

5370

* step = swapArguments(body, 0, 1); // swap V <-> T

5371

* }

5372

* if (startIter == null) startIter = MH_getIter;

5373

* MethodHandle[]

5374

* iterVar = { startIter, null, MH_hasNext, retv }, // it = iterator; while (it.hasNext())

5375

* bodyClause = { init, filterArguments(step, 0, nextVal) }; // v = body(v, t, a)

5376

* return loop(iterVar, bodyClause);

5377

* }

5378

* }</pre></blockquote>

5379

*

5380

* @param iterator an optional handle to return the iterator to start the loop.

5381

* If non-{@code null}, the handle must return {@link java.util.Iterator} or a subtype.

5382

* See above for other constraints.

5383

* @param init optional initializer, providing the initial value of the loop variable.

5384

* May be {@code null}, implying a default initial value. See above for other constraints.

5385

* @param body body of the loop, which may not be {@code null}.

5386

* It controls the loop parameters and result type in the standard case (see above for details).

5387

* It must accept its own return type (if non-void) plus a {@code T} parameter (for the iterated values),

5388

* and may accept any number of additional types.

5389

* See above for other constraints.

5390

*

5391

* @return a method handle embodying the iteration loop functionality.

5392

* @throws NullPointerException if the {@code body} handle is {@code null}.

5393

* @throws IllegalArgumentException if any argument violates the above requirements.

*

* @since 9

*/

public static MethodHandle iteratedLoop(MethodHandle iterator, MethodHandle init, MethodHandle body) {

5398

Class<?> iterableType = iteratedLoopChecks(iterator, init, body);

5399

Class<?> returnType = body.type().returnType();

5400

// Android-changed: getConstantHandle is in MethodHandles.

5401

// MethodHandle hasNext = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_iteratePred);

5402

// MethodHandle nextRaw = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_iterateNext);

5403

MethodHandle hasNext = getConstantHandle(MH_iteratePred);

5404

MethodHandle nextRaw = getConstantHandle(MH_iterateNext);

5405

MethodHandle startIter;

5406

MethodHandle nextVal;

5407

{

5408

MethodType iteratorType;

5409

if (iterator == null) {

5410

// derive argument type from body, if available, else use Iterable

5411

// Android-changed: getConstantHandle is in MethodHandles.

5412

// startIter = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_initIterator);

5413

startIter = getConstantHandle(MH_initIterator);

5414

iteratorType = startIter.type().changeParameterType(0, iterableType);

5415

} else {

5416

// force return type to the internal iterator class

5417

iteratorType = iterator.type().changeReturnType(Iterator.class);

5418

startIter = iterator;

5419

}

5420

Class<?> ttype = body.type().parameterType(returnType == void.class ? 0 : 1);

5421

MethodType nextValType = nextRaw.type().changeReturnType(ttype);

5422

5423

// perform the asType transforms under an exception transformer, as per spec.:

5424

try {

5425

startIter = startIter.asType(iteratorType);

5426

nextVal = nextRaw.asType(nextValType);

5427

} catch (WrongMethodTypeException ex) {

5428

throw new IllegalArgumentException(ex);

}

}

MethodHandle retv = null, step = body;

5433

if (returnType != void.class) {

5434

// the simple thing first: in (I V A...), drop the I to get V

5435

retv = dropArguments(identity(returnType), 0, Iterator.class);

5436

// body type signature (V T A...), internal loop types (I V A...)

5437

step = swapArguments(body, 0, 1); // swap V <-> T

}

MethodHandle[]

iterVar = { startIter, null, hasNext, retv },

5442

bodyClause = { init, filterArgument(step, 0, nextVal) };

5443

return loop(iterVar, bodyClause);

5444

}

5445

5446

private static Class<?> iteratedLoopChecks(MethodHandle iterator, MethodHandle init, MethodHandle body) {

5447

Objects.requireNonNull(body);

5448

MethodType bodyType = body.type();

5449

Class<?> returnType = bodyType.returnType();

5450

List<Class<?>> internalParamList = bodyType.parameterList();

5451

// strip leading V value if present

5452

int vsize = (returnType == void.class ? 0 : 1);

5453

if (vsize != 0 && (internalParamList.size() == 0 || internalParamList.get(0) != returnType)) {

5454

// argument list has no "V" => error

5455

MethodType expected = bodyType.insertParameterTypes(0, returnType);

5456

throw misMatchedTypes("body function", bodyType, expected);

5457

} else if (internalParamList.size() <= vsize) {

5458

// missing T type => error

5459

MethodType expected = bodyType.insertParameterTypes(vsize, Object.class);

5460

throw misMatchedTypes("body function", bodyType, expected);

5461

}

5462

List<Class<?>> externalParamList = internalParamList.subList(vsize + 1, internalParamList.size());

5463

Class<?> iterableType = null;

5464

if (iterator != null) {

5465

// special case; if the body handle only declares V and T then

5466

// the external parameter list is obtained from iterator handle

5467

if (externalParamList.isEmpty()) {

5468

externalParamList = iterator.type().parameterList();

5469

}

5470

MethodType itype = iterator.type();

5471

if (!Iterator.class.isAssignableFrom(itype.returnType())) {

5472

throw newIllegalArgumentException("iteratedLoop first argument must have Iterator return type");

5473

}

5474

if (!itype.effectivelyIdenticalParameters(0, externalParamList)) {

5475

MethodType expected = methodType(itype.returnType(), externalParamList);

5476

throw misMatchedTypes("iterator parameters", itype, expected);

5477

}

5478

} else {

5479

if (externalParamList.isEmpty()) {

5480

// special case; if the iterator handle is null and the body handle

5481

// only declares V and T then the external parameter list consists

5482

// of Iterable

5483

externalParamList = Arrays.asList(Iterable.class);

5484

iterableType = Iterable.class;

5485

} else {

5486

// special case; if the iterator handle is null and the external

5487

// parameter list is not empty then the first parameter must be

5488

// assignable to Iterable

5489

iterableType = externalParamList.get(0);

5490

if (!Iterable.class.isAssignableFrom(iterableType)) {

5491

throw newIllegalArgumentException(

5492

"inferred first loop argument must inherit from Iterable: " + iterableType);

}

}

}

if (init != null) {

MethodType initType = init.type();

5498

if (initType.returnType() != returnType ||

5499

!initType.effectivelyIdenticalParameters(0, externalParamList)) {

5500

throw misMatchedTypes("loop initializer", initType, methodType(returnType, externalParamList));

5501

}

5502

}

5503

return iterableType; // help the caller a bit

5504

}

5505

5506

/*non-public*/ static MethodHandle swapArguments(MethodHandle mh, int i, int j) {

5507

// there should be a better way to uncross my wires

5508

int arity = mh.type().parameterCount();

5509

int[] order = new int[arity];

5510

for (int k = 0; k < arity; k++) order[k] = k;

5511

order[i] = j; order[j] = i;

5512

Class<?>[] types = mh.type().parameterArray();

5513

Class<?> ti = types[i]; types[i] = types[j]; types[j] = ti;

5514

MethodType swapType = methodType(mh.type().returnType(), types);

5515

return permuteArguments(mh, swapType, order);

}

/**

* Makes a method handle that adapts a {@code target} method handle by wrapping it in a {@code try-finally} block.

5520

* Another method handle, {@code cleanup}, represents the functionality of the {@code finally} block. Any exception

5521

* thrown during the execution of the {@code target} handle will be passed to the {@code cleanup} handle. The

5522

* exception will be rethrown, unless {@code cleanup} handle throws an exception first. The

5523

* value returned from the {@code cleanup} handle's execution will be the result of the execution of the

5524

* {@code try-finally} handle.

5525

*

5526

* The {@code cleanup} handle will be passed one or two additional leading arguments.

5527

* The first is the exception thrown during the

5528

* execution of the {@code target} handle, or {@code null} if no exception was thrown.

5529

* The second is the result of the execution of the {@code target} handle, or, if it throws an exception,

5530

* a {@code null}, zero, or {@code false} value of the required type is supplied as a placeholder.

5531

* The second argument is not present if the {@code target} handle has a {@code void} return type.

5532

* (Note that, except for argument type conversions, combinators represent {@code void} values in parameter lists

5533

* by omitting the corresponding paradoxical arguments, not by inserting {@code null} or zero values.)

5534

*

5535

* The {@code target} and {@code cleanup} handles must have the same corresponding argument and return types, except

5536

* that the {@code cleanup} handle may omit trailing arguments. Also, the {@code cleanup} handle must have one or

5537

* two extra leading parameters:<ul>

5538

* <li>a {@code Throwable}, which will carry the exception thrown by the {@code target} handle (if any); and

5539

* <li>a parameter of the same type as the return type of both {@code target} and {@code cleanup}, which will carry

5540

* the result from the execution of the {@code target} handle.

5541

* This parameter is not present if the {@code target} returns {@code void}.

5542

* </ul>

5543

*

5544

* The pseudocode for the resulting adapter looks as follows. In the code, {@code V} represents the result type of

5545

* the {@code try/finally} construct; {@code A}/{@code a}, the types and values of arguments to the resulting

5546

* handle consumed by the cleanup; and {@code B}/{@code b}, those of arguments to the resulting handle discarded by

5547

* the cleanup.

5548

* <blockquote><pre>{@code

5549

* V target(A..., B...);

5550

* V cleanup(Throwable, V, A...);

5551

* V adapter(A... a, B... b) {

5552

* V result = (zero value for V);

5553

* Throwable throwable = null;

5554

* try {

5555

* result = target(a..., b...);

5556

* } catch (Throwable t) {

* throwable = t;

* throw t;

* } finally {

* result = cleanup(throwable, result, a...);

* }

* return result;

* }

* }</pre></blockquote>

5565

*

5566

* Note that the saved arguments ({@code a...} in the pseudocode) cannot

5567

* be modified by execution of the target, and so are passed unchanged

5568

* from the caller to the cleanup, if it is invoked.

5569

*

5570

* The target and cleanup must return the same type, even if the cleanup

5571

* always throws.

5572

* To create such a throwing cleanup, compose the cleanup logic

5573

* with {@link #throwException throwException},

5574

* in order to create a method handle of the correct return type.

5575

*

5576

* Note that {@code tryFinally} never converts exceptions into normal returns.

5577

* In rare cases where exceptions must be converted in that way, first wrap

5578

* the target with {@link #catchException(MethodHandle, Class, MethodHandle)}

5579

* to capture an outgoing exception, and then wrap with {@code tryFinally}.

5580

*

5581

* It is recommended that the first parameter type of {@code cleanup} be

5582

* declared {@code Throwable} rather than a narrower subtype. This ensures

5583

* {@code cleanup} will always be invoked with whatever exception that

5584

* {@code target} throws. Declaring a narrower type may result in a

5585

* {@code ClassCastException} being thrown by the {@code try-finally}

5586

* handle if the type of the exception thrown by {@code target} is not

5587

* assignable to the first parameter type of {@code cleanup}. Note that

5588

* various exception types of {@code VirtualMachineError},

5589

* {@code LinkageError}, and {@code RuntimeException} can in principle be

5590

* thrown by almost any kind of Java code, and a finally clause that

5591

* catches (say) only {@code IOException} would mask any of the others

5592

* behind a {@code ClassCastException}.

5593

*

5594

* @param target the handle whose execution is to be wrapped in a {@code try} block.

5595

* @param cleanup the handle that is invoked in the finally block.

5596

*

5597

* @return a method handle embodying the {@code try-finally} block composed of the two arguments.

5598

* @throws NullPointerException if any argument is null

5599

* @throws IllegalArgumentException if {@code cleanup} does not accept

5600

* the required leading arguments, or if the method handle types do

5601

* not match in their return types and their

5602

* corresponding trailing parameters

5603

*

5604

* @see MethodHandles#catchException(MethodHandle, Class, MethodHandle)

5605

* @since 9

5606

*/

5607

public static MethodHandle tryFinally(MethodHandle target, MethodHandle cleanup) {

5608

List<Class<?>> targetParamTypes = target.type().parameterList();

5609

Class<?> rtype = target.type().returnType();

5610

5611

tryFinallyChecks(target, cleanup);

5612

5613

// Match parameter lists: if the cleanup has a shorter parameter list than the target, add ignored arguments.

5614

// The cleanup parameter list (minus the leading Throwable and result parameters) must be a sublist of the

5615

// target parameter list.

5616

cleanup = dropArgumentsToMatch(cleanup, (rtype == void.class ? 1 : 2), targetParamTypes, 0);

5617

5618

// Ensure that the intrinsic type checks the instance thrown by the

5619

// target against the first parameter of cleanup

5620

cleanup = cleanup.asType(cleanup.type().changeParameterType(0, Throwable.class));

5621

5622

// Use asFixedArity() to avoid unnecessary boxing of last argument for VarargsCollector case.

5623

// Android-changed: use Transformer implementation.

5624

// return MethodHandleImpl.makeTryFinally(target.asFixedArity(), cleanup.asFixedArity(), rtype, targetParamTypes);

5625

return new Transformers.TryFinally(target.asFixedArity(), cleanup.asFixedArity());

5626

}

5627

5628

private static void tryFinallyChecks(MethodHandle target, MethodHandle cleanup) {

5629

Class<?> rtype = target.type().returnType();

5630

if (rtype != cleanup.type().returnType()) {

5631

throw misMatchedTypes("target and return types", cleanup.type().returnType(), rtype);

5632

}

5633

MethodType cleanupType = cleanup.type();

5634

if (!Throwable.class.isAssignableFrom(cleanupType.parameterType(0))) {

5635

throw misMatchedTypes("cleanup first argument and Throwable", cleanup.type(), Throwable.class);

5636

}

5637

if (rtype != void.class && cleanupType.parameterType(1) != rtype) {

5638

throw misMatchedTypes("cleanup second argument and target return type", cleanup.type(), rtype);

5639

}

5640

// The cleanup parameter list (minus the leading Throwable and result parameters) must be a sublist of the

5641

// target parameter list.

5642

int cleanupArgIndex = rtype == void.class ? 1 : 2;

5643

if (!cleanupType.effectivelyIdenticalParameters(cleanupArgIndex, target.type().parameterList())) {

5644

throw misMatchedTypes("cleanup parameters after (Throwable,result) and target parameter list prefix",

5645

cleanup.type(), target.type());

}

}

/**

* Creates a table switch method handle, which can be used to switch over a set of target

5651

* method handles, based on a given target index, called selector.

5652

*

5653

* For a selector value of {@code n}, where {@code n} falls in the range {@code [0, N)},

5654

* and where {@code N} is the number of target method handles, the table switch method

5655

* handle will invoke the n-th target method handle from the list of target method handles.

5656

*

5657

* For a selector value that does not fall in the range {@code [0, N)}, the table switch

5658

* method handle will invoke the given fallback method handle.

5659

*

5660

* All method handles passed to this method must have the same type, with the additional

5661

* requirement that the leading parameter be of type {@code int}. The leading parameter

5662

* represents the selector.

5663

*

5664

* Any trailing parameters present in the type will appear on the returned table switch

5665

* method handle as well. Any arguments assigned to these parameters will be forwarded,

5666

* together with the selector value, to the selected method handle when invoking it.

5667

*

5668

* @apiNote Example:

5669

* The cases each drop the {@code selector} value they are given, and take an additional

5670

* {@code String} argument, which is concatenated (using {@link String#concat(String)})

5671

* to a specific constant label string for each case:

5672

* <blockquote><pre>{@code

5673

* MethodHandles.Lookup lookup = MethodHandles.lookup();

5674

* MethodHandle caseMh = lookup.findVirtual(String.class, "concat",

5675

* MethodType.methodType(String.class, String.class));

5676

* caseMh = MethodHandles.dropArguments(caseMh, 0, int.class);

5677

*

5678

* MethodHandle caseDefault = MethodHandles.insertArguments(caseMh, 1, "default: ");

5679

* MethodHandle case0 = MethodHandles.insertArguments(caseMh, 1, "case 0: ");

5680

* MethodHandle case1 = MethodHandles.insertArguments(caseMh, 1, "case 1: ");

5681

*

5682

* MethodHandle mhSwitch = MethodHandles.tableSwitch(

* caseDefault,

* case0,

* case1

* );

*

* assertEquals("default: data", (String) mhSwitch.invokeExact(-1, "data"));

5689

* assertEquals("case 0: data", (String) mhSwitch.invokeExact(0, "data"));

5690

* assertEquals("case 1: data", (String) mhSwitch.invokeExact(1, "data"));

5691

* assertEquals("default: data", (String) mhSwitch.invokeExact(2, "data"));

5692

* }</pre></blockquote>

5693

*

5694

* @param fallback the fallback method handle that is called when the selector is not

5695

* within the range {@code [0, N)}.

5696

* @param targets array of target method handles.

5697

* @return the table switch method handle.

5698

* @throws NullPointerException if {@code fallback}, the {@code targets} array, or any

5699

* any of the elements of the {@code targets} array are

5700

* {@code null}.

5701

* @throws IllegalArgumentException if the {@code targets} array is empty, if the leading

5702

* parameter of the fallback handle or any of the target

5703

* handles is not {@code int}, or if the types of

5704

* the fallback handle and all of target handles are

5705

* not the same.

5706

*/

5707

public static MethodHandle tableSwitch(MethodHandle fallback, MethodHandle... targets) {

5708

Objects.requireNonNull(fallback);

5709

Objects.requireNonNull(targets);

5710

targets = targets.clone();

5711

MethodType type = tableSwitchChecks(fallback, targets);

5712

// Android-changed: use a Transformer for the implementation.

5713

// return MethodHandleImpl.makeTableSwitch(type, fallback, targets);

5714

return new Transformers.TableSwitch(type, fallback, targets);

5715

}

5716

5717

private static MethodType tableSwitchChecks(MethodHandle defaultCase, MethodHandle[] caseActions) {

5718

if (caseActions.length == 0)

5719

throw new IllegalArgumentException("Not enough cases: " + Arrays.toString(caseActions));

5720

5721

MethodType expectedType = defaultCase.type();

5722

5723

if (!(expectedType.parameterCount() >= 1) || expectedType.parameterType(0) != int.class)

5724

throw new IllegalArgumentException(

5725

"Case actions must have int as leading parameter: " + Arrays.toString(caseActions));

5726

5727

for (MethodHandle mh : caseActions) {

5728

Objects.requireNonNull(mh);

5729

// Android-changed: MethodType's not interned.

5730

// if (mh.type() != expectedType)

5731

if (!mh.type().equals(expectedType))

5732

throw new IllegalArgumentException(

5733

"Case actions must have the same type: " + Arrays.toString(caseActions));

}

return expectedType;

}

// BEGIN Android-added: Code from OpenJDK's MethodHandleImpl.

5740

5741

/**

5742

* This method is bound as the predicate in {@linkplain MethodHandles#countedLoop(MethodHandle, MethodHandle,

5743

* MethodHandle) counting loops}.

5744

*

5745

* @param limit the upper bound of the parameter, statically bound at loop creation time.

5746

* @param counter the counter parameter, passed in during loop execution.

5747

*

5748

* @return whether the counter has reached the limit.

5749

* @hide

5750

*/

5751

public static boolean countedLoopPredicate(int limit, int counter) {

5752

return counter < limit;

}

/**

* This method is bound as the step function in {@linkplain MethodHandles#countedLoop(MethodHandle, MethodHandle,

5757

* MethodHandle) counting loops} to increment the counter.

5758

*

5759

* @param limit the upper bound of the loop counter (ignored).

5760

* @param counter the loop counter.

5761

*

5762

* @return the loop counter incremented by 1.

5763

* @hide

5764

*/

5765

public static int countedLoopStep(int limit, int counter) {

return counter + 1;

}

/**

* This is bound to initialize the loop-local iterator in {@linkplain MethodHandles#iteratedLoop iterating loops}.

5771

*

5772

* @param it the {@link Iterable} over which the loop iterates.

5773

*

5774

* @return an {@link Iterator} over the argument's elements.

5775

* @hide

5776

*/

5777

public static Iterator<?> initIterator(Iterable<?> it) {

5778

return it.iterator();

}

/**

* This method is bound as the predicate in {@linkplain MethodHandles#iteratedLoop iterating loops}.

5783

*

5784

* @param it the iterator to be checked.

5785

*

5786

* @return {@code true} iff there are more elements to iterate over.

5787

* @hide

5788

*/

5789

public static boolean iteratePredicate(Iterator<?> it) {

return it.hasNext();

}

/**

* This method is bound as the step for retrieving the current value from the iterator in {@linkplain

5795

* MethodHandles#iteratedLoop iterating loops}.

5796

*

5797

* @param it the iterator.

5798

*

5799

* @return the next element from the iterator.

5800

* @hide

5801

*/

5802

public static Object iterateNext(Iterator<?> it) {

return it.next();

}

// Indexes into constant method handles:

5807

static final int

5808

MH_cast = 0,

5809

MH_selectAlternative = 1,

5810

MH_copyAsPrimitiveArray = 2,

5811

MH_fillNewTypedArray = 3,

5812

MH_fillNewArray = 4,

5813

MH_arrayIdentity = 5,

5814

MH_countedLoopPred = 6,

5815

MH_countedLoopStep = 7,

MH_initIterator = 8,

MH_iteratePred = 9,

MH_iterateNext = 10,

MH_Array_newInstance = 11,

5820

MH_LIMIT = 12;

5821

5822

static MethodHandle getConstantHandle(int idx) {

5823

MethodHandle handle = HANDLES[idx];

5824

if (handle != null) {

5825

return handle;

5826

}

5827

return setCachedHandle(idx, makeConstantHandle(idx));

5828

}

5829

5830

private static synchronized MethodHandle setCachedHandle(int idx, final MethodHandle method) {

5831

// Simulate a CAS, to avoid racy duplication of results.

5832

MethodHandle prev = HANDLES[idx];

if (prev != null) {

return prev;

}

HANDLES[idx] = method;

return method;

}

// Local constant method handles:

5841

private static final @Stable MethodHandle[] HANDLES = new MethodHandle[MH_LIMIT];

5842

5843

private static MethodHandle makeConstantHandle(int idx) {

5844

try {

5845

// Android-added: local IMPL_LOOKUP.

5846

final Lookup IMPL_LOOKUP = MethodHandles.Lookup.IMPL_LOOKUP;

5847

switch (idx) {

5848

// Android-removed: not-used.

5849

/*

5850

case MH_cast:

5851

return IMPL_LOOKUP.findVirtual(Class.class, "cast",

5852

MethodType.methodType(Object.class, Object.class));

5853

case MH_copyAsPrimitiveArray:

5854

return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "copyAsPrimitiveArray",

5855

MethodType.methodType(Object.class, Wrapper.class, Object[].class));

5856

case MH_arrayIdentity:

5857

return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "identity",

5858

MethodType.methodType(Object[].class, Object[].class));

5859

case MH_fillNewArray:

5860

return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "fillNewArray",

5861

MethodType.methodType(Object[].class, Integer.class, Object[].class));

5862

case MH_fillNewTypedArray:

5863

return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "fillNewTypedArray",

5864

MethodType.methodType(Object[].class, Object[].class, Integer.class, Object[].class));

5865

case MH_selectAlternative:

5866

return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "selectAlternative",

5867

MethodType.methodType(MethodHandle.class, boolean.class, MethodHandle.class, MethodHandle.class));

5868

*/

5869

case MH_countedLoopPred:

5870

// Android-changed: methods moved to this file.

5871

// return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "countedLoopPredicate",

5872

// MethodType.methodType(boolean.class, int.class, int.class));

5873

return IMPL_LOOKUP.findStatic(MethodHandles.class, "countedLoopPredicate",

5874

MethodType.methodType(boolean.class, int.class, int.class));

5875

case MH_countedLoopStep:

5876

// Android-changed: methods moved to this file.

5877

// return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "countedLoopStep",

5878

// MethodType.methodType(int.class, int.class, int.class));

5879

return IMPL_LOOKUP.findStatic(MethodHandles.class, "countedLoopStep",

5880

MethodType.methodType(int.class, int.class, int.class));

5881

case MH_initIterator:

5882

// Android-changed: methods moved to this file.

5883

// return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "initIterator",

5884

// MethodType.methodType(Iterator.class, Iterable.class));

5885

return IMPL_LOOKUP.findStatic(MethodHandles.class, "initIterator",

5886

MethodType.methodType(Iterator.class, Iterable.class));

5887

case MH_iteratePred:

5888

// Android-changed: methods moved to this file.

5889

// return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "iteratePredicate",

5890

// MethodType.methodType(boolean.class, Iterator.class));

5891

return IMPL_LOOKUP.findStatic(MethodHandles.class, "iteratePredicate",

5892

MethodType.methodType(boolean.class, Iterator.class));

5893

case MH_iterateNext:

5894

// Android-changed: methods moved to this file.

5895

// return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "iterateNext",

5896

// MethodType.methodType(Object.class, Iterator.class));

5897

return IMPL_LOOKUP.findStatic(MethodHandles.class, "iterateNext",

5898

MethodType.methodType(Object.class, Iterator.class));

5899

// Android-removed: not-used.

5900

/*

5901

case MH_Array_newInstance:

5902

return IMPL_LOOKUP.findStatic(Array.class, "newInstance",

5903

MethodType.methodType(Object.class, Class.class, int.class));

5904

*/

5905

}

5906

} catch (ReflectiveOperationException ex) {

5907

throw newInternalError(ex);

5908

}

5909

5910

throw newInternalError("Unknown function index: " + idx);

5911

}

5912

// END Android-added: Code from OpenJDK's MethodHandleImpl.

5913

}