1.117.3 Get methods

pce <-answer_stack_size: -> cells=int

Statistics on the incremental garbage collection system. Objects created that are not related to any other object are pushed on the answer stack. They are deleted from this stack iff

• They are related to another object
• They are object->lock_objected (or given a named reference)
• The answer-stack is rewinded to a point before the creation of the object.

  Both event-call-back and the execution of a PCE method mark and rewind this stack. Thus

  ?- new(X, point).

  Creates a point and leaves it on the answer-stack, while

  ?- [user].
  create_point :- new(X, point).
  ^D
  ?- send(@prolog, create_point).

  Creates a point, pushes it on the answer-stack. Then rewinds this stack on exit of the host->create_point, garbage collection the point object. Thus

  ?- pceusage(send(@prolog, create_point)).

1. 00 seconds, 0 bytes, 1 created - 1 freed = 0 objects NOTE: pceusage/1 should often be called twice to get the intended result. The first call may create objects in the XPCE/Prolog cache.

pce <-convert: object=unchecked, type=type -> converted=unchecked

The method pce<-convert provides access to type<-check, the PCE type checking and conversion system. The first argument is the object to be checked/converted. The second is the type that should be met.

Equivalent to type<-check, but generally more comfortable as this method will automatically translate a type specification into a type object.

The following example converts anything convertible to an integer to an integer:

convert_to_int(Any, Int) :-
        get(@pce, convert, Any, int, Int).

After which

convert_to_int('78', X)				==> 78
convert_to_int(string('1992'), X)	==> 1992
convert_to_int(hello, X)			fails
convert_to_int(100, X)				==> 100

See also

- type<-check
- type<-convert
- topic Conversion

pce <-core_usage: -> bytes=int

Number of bytes core allocated by PCE. Notes:

1. Memory requested by the X-window libraries or the host-language is not included
2. Memory requested by PCE is never returned to the process. @see pce<-core_wasted @see tool Statistics

pce <-core_wasted: -> bytes=int

Memory allocated by PCE, but currently not in use.

See also

- pce->list_wasted_core
- pce<-core_usage
- tool Statistics

pce <-cpu_time: kind=[{user,system}] -> seconds=real

CPU time used by the process PCE belongs to. When the argument is @default, this is the combined user and system time, otherwise it is the time specified.

Note that the host language is normally part of the same process.

See also

pce->bench

pce <-date: -> string

Requests the system time using the C-library function ctime(3) and returns the result as a string object. The returned string has no trailing newline (as its Unix counterpart). Its format is:

Sun Sep 16 01:03:52 1973

See also class date.

See also

- date<-string
- class date

pce <-deferred_unalloced: -> number=int

Number of objects that has been object->free’d by the user, but are still referenced. To avoid crashes, the memory belonging to such objects is not freed as long as there are references to the object.

pce <-environment_variable: name=name -> value=name

Read named Unix environment variable which’value is returned as a name.

If name is PCEHOME and this is not defined as a Unix environment variable, the value of pce<-home is returned.

Diagnostics: If the variable is not defined pce<-environment_variable fails silently.

See also

pce-home

pce <-fd: -> number=int

Number of remaining unused Unix file-descriptors. When PCE was based on the SunView windowing environment, each window used a file descriptor and an ungraceful error was generated when no more filedescriptors were available.

pce <-instance: class=class, argument=unchecked ... -> created=object|function

Create an object (as Prolog new/2 or Lisp pce-new()). @pce pce<-instance converts the first argument into a class. This process deals with handling class-names rather then class objects and invokes the autoloader if the class does not yet exist (see pce_autoload/2 and pce<-exception_handlers). Next, the method class<-instance is called to create the new instance.

The following function creates a new point object each time it is evaluated:

?(@pce, instance, point, 4, 5)

See also class create, class<-instance and @vmi_new.

See also

class<-instance

pce <-max_integer: -> value=int

Highest/lowest integer value that may be represented using PCE's data-type int or number. Current range:

-2^29 ... 2^29 - 1 (-536870912 ... 536870911)

See also

- class number
- pce<-min_integer

pce <-min_integer: -> value=int

Inherits description from: pce<-max_integer

See also

pce<-max_integer

pce <-object_from_reference: reference=int|name -> object=unchecked

Converts an object name or integer object-reference into an true object:

?- get(@pce, object_from_reference, prolog, Obj)

Obj = @prolog

This is the inverse of object<-object_reference. See also object<-convert. These methods are used seldomly by application programmers.

See also

- object<-object_reference
- pce->for_name_reference

pce <-objects_allocated: -> number=int

Obsolete method returning the same as

get(class(object), no_created, @on, Count)

See class<-no_created and class<-no_freed.

See also

- pce<-objects_freed
- class-no_created
- tool Statistics

pce <-objects_freed: -> number=int

@see class-no_freed @see pce<-objects_allocated @see tool Statistics

pce <-os_error: -> identifier=name

Name indicating the last operating-system generated error. That is, the text that would normally be printed by the Unix utility perror(2). Its use is not encouraged.

See also

pce-last_error

pce <-pid: -> identifier=int

Unix process identifier for this process. May be used to create unique system-wide names. Note that file objects with a proper temporary name may be created using

?- new(TmpFile, file).

See file->initialise.

pce <-unresolved_types: -> chain

Scans @types for types that are of type<-kind, but have no initialised class associated with them. A name that is not the name of an existing class will be converted into a type of kind class. This type is only useful after the class is actually created. This mechanism allows the programmer to refer to classes as a type before defining them.

The most likely cause of this trouble is a misspelled type-name or a forgotten class definition.

pce <-user: -> user=name

Login name of user. On Unix systems this uses either getlogin() or password information from the current UID. On Windows it examines the environment variable %USER%.

See also pce<-user_info.