yuzu/enet
1
0
Fork 0
mirror of https://github.com/lsalzman/enet synced 2024-11-21 14:29:05 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

removing stale files

Browse source
This commit is contained in:
eihrul 2010-05-20 20:43:42 +00:00
parent 13c9411acf
commit f34daadcf1
2 changed files with 0 additions and 442 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

117
design.txt
View file

@ -1,117 +0,0 @@
* Why ENet?
ENet evolved specifically as a UDP networking layer for the multiplayer
first person shooter Cube. Cube necessitated low latency communcation with
data sent out very frequently, so TCP was an unsuitable choice due to its
high latency and stream orientation. UDP, however, lacks many sometimes
necessary features from TCP such as reliability, sequencing, unrestricted
packet sizes, and connection management. So UDP by itself was not suitable
as a network protocol either. No suitable freely available networking
libraries existed at the time of ENet's creation to fill this niche.
UDP and TCP could have been used together in Cube to benefit somewhat
from both of their features, however, the resulting combinations of protocols
still leaves much to be desired. TCP lacks multiple streams of communication
without resorting to opening many sockets and complicates delineation of
packets due to its buffering behavior. UDP lacks sequencing, connection
management, management of bandwidth resources, and imposes limitations on
the size of packets. A significant investment is required to integrate these
two protocols, and the end result is worse off in features and performance
than the uniform protocol presented by ENet.
ENet thus attempts to address these issues and provide a single, uniform
protocol layered over UDP to the developer with the best features of UDP and
TCP as well as some useful features neither provide, with a much cleaner
integration than any resulting from a mixture of UDP and TCP.
* Connection management
ENet provides a simple connection interface over which to communicate
with a foreign host. The liveness of the connection is actively monitored
by pinging the foreign host at frequent intervals, and also monitors the
network conditions from the local host to the foreign host such as the
mean round trip time and packet loss in this fashion.
* Sequencing
Rather than a single byte stream that complicates the delineation
of packets, ENet presents connections as multiple, properly sequenced packet
streams that simplify the transfer of various types of data.
ENet provides sequencing for all packets by assigning to each sent
packet a sequence number that is incremented as packets are sent. ENet
guarentees that no packet with a higher sequence number will be delivered
before a packet with a lower sequence number, thus ensuring packets are
delivered exactly in the order they are sent.
For unreliable packets, ENet will simply discard the lower sequence
number packet if a packet with a higher sequence number has already been
delivered. This allows the packets to be dispatched immediately as they
arrive, and reduce latency of unreliable packets to an absolute minimum.
For reliable packets, if a higher sequence number packet arrives, but the
preceding packets in the sequence have not yet arrived, ENet will stall
delivery of the higher sequence number packets until its predecessors
have arrived.
* Channels
Since ENet will stall delivery of reliable packets to ensure proper
sequencing, and consequently any packets of higher sequence number whether
reliable or unreliable, in the event the reliable packet's predecessors
have not yet arrived, this can introduce latency into the delivery of other
packets which may not need to be as strictly ordered with respect to the
packet that stalled their delivery.
To combat this latency and reduce the ordering restrictions on packets,
ENet provides multiple channels of communication over a given connection.
Each channel is independently sequenced, and so the delivery status of
a packet in one channel will not stall the delivery of other packets
in another channel.
* Reliability
ENet provides optional reliability of packet delivery by ensuring the
foreign host acknowledges receipt of all reliable packets. ENet will attempt
to resend the packet up to a reasonable amount of times, if no acknowledgement
of the packet's receipt happens within a specified timeout. Retry timeouts
are progressive and become more lenient with every failed attempt to allow
for temporary turbulence in network conditions.
* Fragmentation and reassembly
ENet will send and deliver packets regardless of size. Large packets are
fragmented into many smaller packets of suitable size, and reassembled on
the foreign host to recover the original packet for delivery. The process
is entirely transparent to the developer.
* Aggregation
ENet aggregates all protocol commands, including acknowledgements and
packet transfer, into larger protocol packets to ensure the proper utilization
of the connection and to limit the opportunities for packet loss that might
otherwise result in further delivery latency.
* Adaptability
ENet provides an in-flight data window for reliable packets to ensure
connections are not overwhelmed by volumes of packets. It also provides a
static bandwidth allocation mechanism to ensure the total volume of packets
sent and received to a host don't exceed the host's capabilities. Further,
ENet also provides a dynamic throttle that responds to deviations from normal
network connections to rectify various types of network congestion by further
limiting the volume of packets sent.
* Portability
ENet works on Windows and any other Unix or Unix-like platform providing
a BSD sockets interface. The library has a small and stable code base that
can easily be extended to support other platforms and integrates easily.
* Freedom
ENet demands no royalties and doesn't carry a viral license that would
restrict you in how you might use it in your programs. ENet is licensed under
a short-and-sweet MIT-style license, which gives you the freedom to do anything
you want with it (well, almost anything).

325
tutorial.txt
View file

@ -1,325 +0,0 @@
* Using ENet
Before using ENet, you must call enet_initialize() to initialize the
library. Upon program exit, you should call enet_deinitialize() so that
the library may clean up any used resources.
i.e.
int
main (int argc, char ** argv)
{
if (enet_initialize () != 0)
{
fprintf (stderror, "An error occurred while initializing ENet.\n");
return EXIT_FAILURE;
}
atexit (enet_deinitialize);
...
...
...
}
* Creating an ENet server
Servers in ENet are constructed with enet_host_create(). You must specify
an address on which to receive data and new connections, as well as the maximum
allowable numbers of connected peers. You may optionally specify the incoming
and outgoing bandwidth of the server in bytes per second so that ENet may try
to statically manage bandwidth resources among connected peers in addition to
its dynamic throttling algorithm; specifying 0 for these two options will cause
ENet to rely entirely upon its dynamic throttling algorithm to manage
bandwidth.
When done with a host, the host may be destroyed with enet_host_destroy().
All connected peers to the host will be reset, and the resources used by
the host will be freed.
i.e.
ENetAddress address;
ENetHost * server;
/* Bind the server to the default localhost.
* A specific host address can be specified by
* enet_address_set_host (& address, "x.x.x.x");
*/
address.host = ENET_HOST_ANY;
/* Bind the server to port 1234. */
address.port = 1234;
server = enet_host_create (& address /* the address to bind the server host to */,
32 /* allow up to 32 clients and/or outgoing connections */,
0 /* assume any amount of incoming bandwidth */,
0 /* assume any amount of outgoing bandwidth */);
if (server == NULL)
{
fprintf (stderr,
"An error occurred while trying to create an ENet server host.\n");
exit (EXIT_FAILURE);
}
...
...
...
enet_host_destroy(server);
* Creating an ENet client
Clients in ENet are similarly constructed with enet_host_create() when no
address is specified to bind the host to. Bandwidth may be specified for the
client host as in the above example. The peer count controls the maximum number
of connections to other server hosts that may be simultaneously open.
i.e.
ENetHost * client;
clienet = enet_host_create (NULL /* create a client host */,
1 /* only allow 1 outgoing connection */,
57600 / 8 /* 56K modem with 56 Kbps downstream bandwidth */,
14400 / 8 /* 56K modem with 14 Kbps upstream bandwidth */);
if (client == NULL)
{
fprintf (stderr,
"An error occurred while trying to create an ENet client host.\n");
exit (EXIT_FAILURE);
}
...
...
...
enet_host_destroy(client);
* Managing an ENet host
ENet uses a polled event model to notify the programmer of significant
events. ENet hosts are polled for events with enet_host_service(), where an
optional timeout value in milliseconds may be specified to control how long
ENet will poll; if a timeout of 0 is specified, enet_host_service() will
return immediately if there are no events to dispatch. enet_host_service()
will return 1 if an event was dispatched within the specified timeout.
Currently there are only four types of significant events in ENet:
An event of type ENET_EVENT_TYPE_NONE is returned if no event occurred
within the specified time limit. enet_host_service() will return 0
with this event.
An event of type ENET_EVENT_TYPE_CONNECT is returned when either a new client
host has connected to the server host or when an attempt to establish a
connection with a foreign host has succeeded. Only the "peer" field of the
event structure is valid for this event and contains the newly connected peer.
An event of type ENET_EVENT_TYPE_RECEIVE is returned when a packet is received
from a connected peer. The "peer" field contains the peer the packet was
received from, "channelID" is the channel on which the packet was sent, and
"packet" is the packet that was sent. The packet contained in the "packet"
field must be destroyed with enet_packet_destroy() when you are done
inspecting its contents.
An event of type ENET_EVENT_TYPE_DISCONNECT is returned when a connected peer
has either explicitly disconnected or timed out. Only the "peer" field of the
event structure is valid for this event and contains the peer that
disconnected. Only the "data" field of the peer is still valid on a
disconnect event and must be explicitly reset.
i.e.
ENetEvent event;
/* Wait up to 1000 milliseconds for an event. */
while (enet_host_service (client, & event, 1000) > 0)
{
switch (event.type)
{
case ENET_EVENT_TYPE_CONNECT:
printf ("A new client connected from %x:%u.\n",
event.peer -> address.host,
event.peer -> address.port);
/* Store any relevant client information here. */
event.peer -> data = "Client information";
break;
case ENET_EVENT_TYPE_RECEIVE:
printf ("A packet of length %u containing %s was received from %s on channel %u.\n",
event.packet -> dataLength,
event.packet -> data,
event.peer -> data,
event.channelID);
/* Clean up the packet now that we're done using it. */
enet_packet_destroy (event.packet);
break;
case ENET_EVENT_TYPE_DISCONNECT:
printf ("%s disconected.\n", event.peer -> data);
/* Reset the peer's client information. */
event.peer -> data = NULL;
}
}
...
...
...
* Sending a packet to an ENet peer
Packets in ENet are created with enet_packet_create(), where the size of
the packet must be specified. Optionally, initial data may be specified to
copy into the packet.
Certain flags may also be supplied to enet_packet_create() to control
various packet features:
ENET_PACKET_FLAG_RELIABLE specifies that the packet must use reliable delivery.
A reliable packet is guarenteed to be delivered, and a number of retry attempts
will be made until an acknowledgement is received from the foreign host the
packet is sent to. If a certain number of retry attempts is reached without
any acknowledgement, ENet will assume the peer has disconnected and forcefully
reset the connection. If this flag is not specified, the packet is assumed
an unreliable packet, and no retry attempts will be made nor acknowledgements
generated.
A packet may be resized (extended or truncated) with enet_packet_resize().
A packet is sent to a foreign host with enet_peer_send(). enet_peer_send()
accepts a channel id over which to send the packet to a given peer. Once the
packet is handed over to ENet with enet_peer_send(), ENet will handle its
deallocation and enet_packet_destroy() should not be used upon it.
One may also use enet_host_broadcast() to send a packet to all connected
peers on a given host over a specified channel id, as with enet_peer_send().
Queued packets will be sent on a call to enet_host_service().
Alternatively, enet_host_flush() will send out queued packets without
dispatching any events.
i.e.
/* Create a reliable packet of size 7 containing "packet\0" */
ENetPacket * packet = enet_packet_create ("packet",
strlen ("packet") + 1,
ENET_PACKET_FLAG_RELIABLE);
/* Extend the packet so and append the string "foo", so it now
* contains "packetfoo\0"
*
enet_packet_resize (packet, strlen ("packetfoo") + 1);
strcpy (& packet -> data [strlen ("packet")], "foo");
/* Send the packet to the peer over channel id 3.
* One could also broadcast the packet by
* enet_host_broadcast (host, 3, packet);
*/
enet_peer_send (peer, 3, packet);
...
...
...
/* One could just use enet_host_service() instead. */
enet_host_flush (host);
* Disconnecting an ENet peer
Peers may be gently disconnected with enet_peer_disconnect(). A disconnect
request will be sent to the foreign host, and ENet will wait for an
acknowledgement from the foreign host before finally disconnecting. An
event of type ENET_EVENT_TYPE_DISCONNECT will be generated once the
disconnection succeeds. Normally timeouts apply to the disconnect
acknowledgement, and so if no acknowledgement is received after a length
of time the peer will be forcefully disconnected.
enet_peer_reset() will forcefully disconnect a peer. The foreign host
will get no notification of a disconnect and will time out on the foreign
host. No event is generated.
i.e.
ENetEvent event;
enet_peer_disconnect (& client -> peers [0], 0);
/* Allow up to 3 seconds for the disconnect to succeed
* and drop any packets received packets.
*/
while (enet_host_service (client, & event, 3000) > 0)
{
switch (event.type)
{
case ENET_EVENT_TYPE_RECEIVE:
enet_packet_destroy (event.packet);
break;
case ENET_EVENT_TYPE_DISCONNECT:
puts ("Disconnection succeeded.");
return;
...
...
...
}
}
/* We've arrived here, so the disconnect attempt didn't succeed yet.
* Force the connection down.
*/
enet_peer_reset (& client -> peers [0]);
...
...
...
* Connecting to an ENet host
A connection to a foregin host is initiated with enet_host_connect().
It accepts the address of a foreign host to connect to, and the number of
channels that should be allocated for communication. If N channels are
allocated for use, their channel ids will be numbered 0 through N-1.
A peer representing the connection attempt is returned, or NULL if there
were no available peers over which to initiate the connection. When the
connection attempt succeeds, an event of type ENET_EVENT_TYPE_CONNECT will
be generated. If the connection attempt times out or otherwise fails, an
event of type ENET_EVENT_TYPE_DISCONNECT will be generated.
i.e.
ENetAddress address;
ENetEvent event;
ENetPeer *peer;
/* Connect to some.server.net:1234. */
enet_address_set_host (& address, "some.server.net");
address.port = 1234;
/* Initiate the connection, allocating the two channels 0 and 1. */
peer = enet_host_connect (client, & address, 2);
if (peer == NULL)
{
fprintf (stderr,
"No available peers for initiating an ENet connection.\n");
exit (EXIT_FAILURE);
}
/* Wait up to 5 seconds for the connection attempt to succeed.
if (enet_host_service (client, & event, 5000) > 0 &&
event.type == ENET_EVENT_TYPE_CONNECT)
{
puts ("Connection to some.server.net:1234 succeeded.");
...
...
...
}
else
{
/* Either the 5 seconds are up or a disconnect event was
* received. Reset the peer in the event the 5 seconds
* had run out without any significant event.
*/
enet_peer_reset (peer);
puts ("Connection to some.server.net:1234 failed.");
}
...
...
...