Introduction
============

Ice-E is a compact subset of Ice designed for embedded environments
while retaining many of the features that have made Ice such a
compelling alternative for distributed applications.


Comparing Ice-E and Ice
=======================

In order to reduce the size of the Ice-E run time, several Ice
features have been removed, and others are optional. The differences
are discussed in the sections below.

Concurrency Models
------------------

Ice-E supports only the thread-per-connection server-side concurrency
model; the thread pool concurrency model is not supported.

Applications that make nested callbacks must be aware of the following
limitations of the thread-per-connection model:

* For bidirectional connections, the nested callback must be a oneway
  invocation.

* For regular (unidirectional) connections, the nested callback can
  be a twoway invocation.

* Only one level of nested callbacks is allowed.

For the client-side, Ice-E supports the thread-per-connection model as
well as a blocking concurrency model that can provide better
performance results. Set the configuration property Ice.Blocking=1 to
enable the blocking model. In addition to the limitations of the
thread-per-connection model described above, the blocking model also
disallows the use of bidirectional connections.

Transports
----------

Ice-E includes support for the TCP transport; UDP and SSL are not
supported. The built-in TCP transport can be replaced with one of your
own.

Objects by Value
----------------

Ice-E does not allow Slice classes to be transmitted by value.

Servant Locators
----------------

Ice-E does not support servant locators. Ice-E applications must
use the active servant map.

Collocation Optimization
------------------------

Support for collocation optimization has been removed. Note that
Ice-E applications are still able to make invocations on collocated
servants, but those invocations are not optimized and therefore will
be marshaled and sent over the built-in transport.

Other Removed Features
----------------------

Ice-E has also eliminated the following features:

* Asynchronous invocation and dispatch
* Streaming APIs
* Active connection management
* Protocol compression
* Ice::Application and Ice::Service classes
* Local interfaces.

Optional Features
-----------------

Support for routers, locators and batch messages is enabled by
default but can be removed in order to further reduce the size of
the Ice-E run time. See the "Configuration" section below for more
information.

Compatibility
-------------

Ice-E and Ice share the same C++ mapping and remain source-code
compatible, given the limitations described above. Furthermore,
since the two products also share the same protocol, a distributed
system can use any combination of Ice and Ice-E applications.

Customization
-------------

If the current features do not meet your requirements, ZeroC can
customize Ice-E for commercial users. Please contact us at
info@zeroc.com for more information.


Run-time Libraries
==================

In order to minimize the size of Ice-E applications, two versions of
the run time library are provided:

* The "client" library is suitable for applications requiring only
  client-side functionality.

* The "server" library supports client- and server-side functionality.

A simple rule of thumb is to use the server library if your program
creates an object adapter, otherwise you can use the client library.

Users of the client library must define the preprocessor macro
ICEE_PURE_CLIENT when compiling an application as well as link with
the appropriate run time library.


Configuration
=============

You may build the Ice-E run time libraries with certain components
disabled in order to further reduce the size of your applications. The
default configuration enables all of the optional components, but you
can selectively disable them by editing the file include/IceE/Config.h
and commenting out their corresponding preprocessor macros. The
optional components are described below. For more information on these
features, please refer to the Ice manual.

Router Support
--------------

If ICEE_HAS_ROUTER is defined, the Ice-E libraries will include
support for routers. This component is necessary in order to use
Ice-E with the Glacier2 router.

Applications that use routers often also receive callbacks from remote
servers. These applications must use the server library, because the
client library does not provide support for callbacks.

Locator Support
---------------

If ICEE_HAS_LOCATOR is defined, the Ice-E libraries will include
support for locators. This component is necessary in order to use
indirect proxies in Ice-E.

Batch Messages Support
----------------------

If ICEE_HAS_BATCH is defined, the Ice-E client library will include
support for sending batch messages. This feature cannot be disabled
in the server library.

Blocking Client Support
-----------------------

If ICEE_PURE_BLOCKING_CLIENT is defined, the Ice-E client library will
include support only for the blocking client-side concurrency model. 

Wstring and String Converter Support
------------------------------------

If ICEE_HAS_WSTRING is defined, the Ice-E libraries will include 
support for using wide strings as well as configuring custom string
converters.


Installation
============

For installation instructions, please refer to the INSTALL.* file for
your platform.
