FunctionPackage: net.jlinkerToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.2
The object described on this page has been modified in the 8.2 release; see the Release Notes.
8.1 version

make-immediate-object

Arguments: x &optional type (symcase :read) (pkcase symcase)

Update: a patch released in March, 2011, modified this function to ignore the symcase and pkcase optional arguments. An error will be signaled if this function is called with values for those arguments other than the defaults shown (that is, both :read).

The purpose of this function is to create a transfer object that will transmit the value of the Lisp arguement to Java. If the Lisp object cannot be transmitted by value, the function returns nil. The function make-dist-object always creates a transfer object - when the Lisp object cannot be transmitted by value, make-dist-object creates a remote reference.

If the second (type)argument to make-immediate-object is omitted or nil, the conversion is done following the default conversion rules described in the Data Types and Conversions section of jlinker.htm. If the type argument is not nil, then it must be a keyword that constrains how the Lisp value should be transmitted to Java. The table below shows how the Lisp type of the first argument, x, and the second argument, type, combine to control the resulting Java type:

Lisp Type of x type is :ref type is :boolean type is :byte type is :short type is :int
bignum See Note 1 boolean byte short int
integer int boolean byte short int
real See Note 1 boolean double double double
string See Note 1 boolean String String String
character char boolean char char char
(array (signed-byte 32) (*)) See Note 1 boolean byte[] short[] int[]
(array double-float (*)) See Note 1 boolean double[] double[] double[]
null null boolean byte[] short[] int[]
symbol See Note 3 See Note 1 boolean See Note 1 See Note 1 See Note 1
cons See Note 2 See Note 1 boolean byte[] short[] int[]
Lisp Type of x type is :long type is :single type is :double type is :string
bignum long int int int
integer long int int int
real double float double double
string String String String String
character char char char char
(array (signed-byte 32) (*)) int[] int[] int[] int[]
(array double-float (*)) double[] float[] double[] double[]
null null float[] double[] String[]
symbol See Note 3 See Note 1 See Note 1 See Note 1 See Note 1
cons See Note 2 See Note 1 float[] double[] String[]

Notes

  1. In this case, make-immediate-object returns nil because the Lisp object may not be passed by value in this way and a remote reference must be created.
  2. When a type is specified and the argument x is a cons, we attempt to make a Java array of the specified type. If an unsuitable value is found in the list, an error is signaled. Integer values must be in the Java int range and get truncated to byte or short if appropriate.

    The Lisp list (1 2 3) is passed to Java as a remote reference in the default conversion case.

    The form (make-immediate-object '(1 2 3) :int) will pass to Java an array of int values.

  3. When the argument x is a symbol, the type argument may be one of the Lisp symbols symbol-value, symbol-function, or class to transmit a remote reference to the corresponding Lisp value.

It may seem less than useful to transmit Lisp symbols to a Java program since symbols are not a useful Java data type. Symbol references are useful to the Java program as values that may be passed back to the Lisp application. Once the symbol reference has been passed to Java it may be returned to Lisp many times with little overhead and yields the same eq symbol in Lisp every time. It is also possible for the Java program to create symbol references with the newDistSym() method.

The symcase and pkcase arguments are ignored. It is an error to specify values for them other than the defauls shown.

See jlinker.htm for more information on the jLinker facility.


Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.2
The object described on this page has been modified in the 8.2 release; see the Release Notes.
8.1 version