How to use the "net" cluster

This page is divided into the following sections:

• vocabulary
• how to be a client
• how to be a server
• how to use the provided servers
• some technical aspects

To be client means trying to reach some server and getting some data from it.

There are two concepts to grasp before making a connection:

• Address: that's the network address of a machine (a "host"), given either by its name or its IP number. The net cluster knows of three kinds of addresses: the host name, the IP address and the local address which represents the local machine.
• Access: it allows to connect to some server that runs on a machine and listens on a port. The net cluster knows of three kinds of accesses: TCP and UDP access, and the special Local access that reaches the local machine.

To be a client, you have to do three things, in that order:

• create an address object
• create an access object, using the address object
• query a stream from the access object

In Liberty Eiffel, you would write it this way:

   connect_to_funet: TERMINAL_INPUT_OUTPUT_STREAM is
      local
         funet: HOST
         tcp: TCP_ACCESS
      do
         create funet.make(once "ftp.funet.fi")
         create tcp.make(funet, 21)
         Result := tcp.stream
      end

(See also the tutorial: class SOCKETS)

To be a server, things are a bit more complex but not tremendously so.

First note that you must know something of the lib/sequencer cluster. You must also be familiar with agents.

To create a server, start by creating an address and an access. The address will filter which connections are allowed¹, and the access port will determine which port the server will listen to.

Now you must create a SOCKET_SERVER, give it one or more agents using the `when_connect' feature. Those agents are called whenever a new client connects; each agent is given the same stream that represents the connection to the client.

Note that having multiple agents is potentially dangerous. Either all the agents cooperate, either having one registered is enough. Remember that all agents share the same stream.

How to use the "storage" cluster

This cluster provides the main collection abstractions and their implementations. This document provides a few hints that may help choosing the most relevant data structure.

Collections

Collections are linear sequences of objects. They are traversable by either using an index (an INTEGER between lower and upper) or an iterator.

The standard library implementations are:

• FAST_ARRAY: a random accessible array of object; lower is zero.
• ARRAY: a random accessible array of object with a variable lower bound (hence just a little bit slower than FAST_ARRAY)
• RING_ARRAY: a random accesisble array with variable bounds and optimized for additions and removals at both ends (used for QUEUE implementation)
• LINKED_LIST: a collection of objects linked together; random access is slower but insertion in the middle is faster.
• TWO_WAY_LINKED_LIST: the same but objects are linked both forward and backward thus allowing efficient iteration in both directions.

Multi-dimentsion collections

COLLECTION2 and COLLECTION3 provide similar facilities for two- and three-dimension object collections.

Maps

Maps provide indexed collections: access to object values using object keys.

The standard library implementations are:

• HASHED_DICTIONARY: the classical hash table. The keys must be HASHABLE. The capacity of those dictionaries is always a prime number; collisions are resolved by linking together the objects with the same hash code (module the table capacity). Therefore a hashed dictionary may contain more elements than its capacity! EST_HASHED_DICTIONARY provides the same data structure but requires an external agent to provide the hash code of a key (therefore alleviating the need for the key to be HASHABLE).
• PYTHON_DICTIONARY: another implementation of hash tables, using Python's algorithm. The keys must be HASHABLE. The capacity is exactly what it says: the number of elements may not exceed the capacity. Collisions are resolved by spreading the elements in the table's array. There are no linked lists, no reference nodes, therefore this implementation is a bit less memory hungry. The capacity is always a power of 2. EXT_PYTHON_DICTIONARY provides the same data structure but requires an external agent to provide the hash code of a key (therefore alleviating the need for the key to be HASHABLE).
• AVL_DICTIONARY: the objects are distributed in an AVL tree using COMPARABLE keys. Because the elements are linked in a tree, there is no capacity (it is meaningless). EXT_AVL_DICTIONARY provides the same data structure but requires an external agent to compare two keys (therefore alleviating the need for the key to be COMPARABLE).
• ZIP is just a pair of collections with the same count. One collection is the list of keys, the other is the list of values.
• ENUMERATE is just a collection with the object indices as key.

Sets

Sets of objects have unique occurrences of each object. Mathematical set operators are available.

The standard library implementations are:

• HASHED_SET and EXT_HASHED_SET
• AVL_SET and EXT_AVL_SET

Repositories

A repository is a collection of STORABLE objects. The aim of this structure is to make objects persistent.

The standard library implementations are:

• JSON_FILE_REPOSITORY loads and stores persistent objects in a file useing a JSON format. JSON_STREAM_REPOSITORY uses input/output streams for data loading and storing, also using a JSON format.
• XML_FILE_REPOSITORY loads and stores persistent objects in a file useing a XML format. XML_STREAM_REPOSITORY uses input/output streams for data loading and storing, also using a XML format.

See also: REPOSITORY_TRANSIENT to register objects that must not be persisted.