3.4.1 The Patterns of basicsocket

AssignGuard is used to detect wrong usage of other patterns, and localHost_IP_number is the number used by convention to indicate the 'this host'. None of them are important for the understanding of the fragment.

sameConnection answers the question of whether this and other wraps the same OS level connection. getPortableAddress returns a portable address for the connection.

Use connect to connect to a passive socket, like those generated by socketgenerator. connect establishes a connection to a (host,port) pair given either as arguments, or stored in the attributes port, host or inetAddr. You should set only one of host and inetAddr, as inetAddr is set to the internet address of host if inetAddr is not set. host is ignored when inetAddr is set.

Host must be given in a format like quercus.daimi.aau.dk or 130.225.16.15. Depending on the network topologi and the whereabouts of this process, some prefixes of the first format may also suffice, notably a format like quercus. The port must be an integer. By convention, port numbers below 5000 are reserved for system administration purposes and for special, well-known services like e-mail and ftp. On the other hand, do not expect to be able to use more than a 16-bit unsigned value (0 through 65535). The value to use when assigning inetAddr must be the four-byte internet address, given as an integer value. E.g. the absolute address 130.225.16.15 is given as the integer 2195787791. The integer must be in the normal byte-order of the platform running the program.

forceTimeout is used to provoke the same response within an ongoing operation as would have been the result of a timeout. This makes it possible to exercise timeout control over an operation from within a co-routine different from the one executing that operation. Moreover, it makes it possible to define a timeout limit for the execution of a number of operations, instead of setting timeouts for each of them. UsageTimeStamp returns an integer value which indicates when this socket was last used. The value makes sense only when compared to usage time stamps of other sockets in this same process. The purpose is to enable a user of many sockets to close the least recently used connection or similarly when and if the process runs out of system resources (e.g. it experiences a to many open files error).

close must be called when done with the socket. Every local idle executes the idle on basicsocket. The global error is called whenever a operation-level error is called and did not handle the error. nonBlockingScope is explained below.

The nonBlockingScope pattern is used for specifying non-blocking communication. This means that operations which cannot begin right away are discontinued. An example is: We try to read from a socket, but no data at all is available to read. If, on the other hand, any irreversible actions have been taken in an operation (e.g. reading a few bytes), it will not be interrupted by the nonBlockingScope mechanism. This means it is always safe to interrupt an operation by enclosing it in a nonBlockingScope, and then later to retry it. It also means that the granularity of scheduling by means of nonBlockingScope is one communication operation; e.g. if the communication partner sends half a block and then takes a break, this process can only execute an idle in the mean time, it cannot switch forth and back between several such ongoing transfers. With each Idle pattern comes a Blocking virtual. This is executed if the current operation is blocking, i.e. if nothing can be done right away and nothing has been done yet. You may extend this virtual to take some action in response to the operation being blocked. If the operation is enclosed in a nonBlockingScope, Blocking gets executed immediately before the operation is interrupted. If you do not want to interrupt the operation, execute continue in a extending of Blocking. (If you are not using a nonBlockingScope, the operation wil automatically continue when possible)

withPE and withIdle are auxiliary patterns used in implementing the scheduling system.