[Spread-cvs] commit: r290 - in trunk: . daemon docs
jonathan at spread.org
jonathan at spread.org
Wed Feb 8 04:11:19 EST 2006
Author: jonathan
Date: 2006-02-08 04:11:18 -0500 (Wed, 08 Feb 2006)
New Revision: 290
Added:
trunk/docs/PORTING
trunk/docs/Short_Buffer_Handling.txt
trunk/license.txt
Removed:
trunk/daemon/PORTING
trunk/daemon/Short_Buffer_Handling.txt
trunk/daemon/license.txt
Log:
Move docs to docs dir. Place license at top level.
Deleted: trunk/daemon/PORTING
===================================================================
--- trunk/daemon/PORTING 2006-02-08 08:46:41 UTC (rev 289)
+++ trunk/daemon/PORTING 2006-02-08 09:11:18 UTC (rev 290)
@@ -1,55 +0,0 @@
-SPREAD: A Reliable Multicast and Group Communication Toolkit
------------------------------------------------------------
-
-PORTING GUIDE:
---------------
-
-This is definitely a work in progress, so email me any comments you have
-at jonathan at cs.jhu.edu.
-
-Basically Spread requires a BSD sockets networking API, and a few fairly
-standard Posix API calls. It was some work to port to Windows, but not
-much in comparison with porting graphical software.
-
-Each supported architecture has an entry in the arch.h file which defines
-all necessary info about each architecture. The arch.h file has three major
-sections. First there is detection code which detects what platform is
-currently being built. Second there is the setting of capability flags
-depending on the built architecture. Third there are some general definitions
-used by all the architectures. For example, the Linux entry looks like this:
-
-/* detect linux */
-#ifdef __linux__
-#define ARCH_PC_LINUX
-#endif
-
-/* Set flags for linux */
-#ifdef ARCH_PC_LINUX
-#define INTSIZE32
-#define ARCH_SCATTER_CONTROL /* should be control if supported */
-#define ARCH_ENDIAN 0x80000080
-#define LOC_INLINE __inline__
-#include <sys/uio.h>
-#define ARCH_SCATTER_SIZE UIO_MAXIOV
-#define HAVE_GOOD_VARGS
-typedef int sockopt_len_t;
-#endif /* ARCH_PC_LINUX */
-
-Essentially all that is required is some knowledge about the sizes of the
-basic C types int and short, what endianness the machine is, and whether
-{recv/send}msg calls use the POSIX msg_control structure or the Solaris like
-acc_rights structure. For endianness, if a machine is little-endian then
-the ARCH_ENDIAN should be set to 0x80000080, if it is big-endian then
-ARCH_ENDIAN should be 0x00000000. The #include is used to grab the definition
-of how large scatters (iovecs) are for each architecture. Since each one stores
-the value in a different variable and in a different include file, we have
-to do this per architecture. If your platform has <stdarg.h> and a working
-implementation of variable arguments (va_list, va_start, va_end) then
-define HAVE_GOOD_VARGS, otherwise we use a different method that works
-everywhere.
-
-The makefile for each architecture are very similar. The main differences
-occur if we can't use gcc on that platform (like IRIX) or if additional
-libraries are required for sockets programs (like Solaris)
-
-
Deleted: trunk/daemon/Short_Buffer_Handling.txt
===================================================================
--- trunk/daemon/Short_Buffer_Handling.txt 2006-02-08 08:46:41 UTC (rev 289)
+++ trunk/daemon/Short_Buffer_Handling.txt 2006-02-08 09:11:18 UTC (rev 290)
@@ -1,86 +0,0 @@
-Short Buffer Handling
-
-The traditional behaivor of networking APIs when a user provided
-buffer is insufficient is to provide as much data as possible and
-truncate the rest. Sometimes the user receives a notice that some data
-was truncated and sometimes no notification is given. Thus it is the
-user's responsiblity to detect when datagrams are too short and
-recover in some way (such as re-requesting data).
-
-The difficulty with using this approach in Spread is that when the
-application has to recover from this some properties of the message
-are lost. For example, if the message was a SAFE message, the other
-members can rightly assume that either all the members will get the
-data or they will not get it because they crash or disconnect from
-Spread . In this case some members might get part of the data, but
-have to recover the rest of it, also the data can be lost even when
-the process continues to execute correctly which makes it difficult
-for the other members to detect the fault.
-
-Essentially because each message has attached meaning, such as
-ordering, or reliability guarantees, unpredictable loss of data in an
-otherwise reliable system compromises the very semantics we want to
-use. It is possible to check for this loss and recover, but the costs
-are significant, especially when weighed against the cost of avoiding
-the problem in the first place. Thus, unlike UDP datagrams, Spread
-messages are designed to be reliable even with short buffers.
-
-The method used is straightforward. Spread will never truncate large
-messages unless you explicitly ask it to. When you call SP receive
-with a data buffer or groups list too short to hold all the data, the
-SP_receive function will return with an error code of GROUPS_TOO_SHORT
-or BUFFER_TOO_SHORT and NO data or groups will be returned. The only
-information that will be returned is in the following parameters:
-
-service_type: set to the correct type for the message. sender is
-empty.
-
-num_groups: set to the number of groups the groups parameter needs to
-accept to avoid a GROUPS TOO SHORT error. This number is returned as a
-negative number. If there were sufficient groups given then a 0 will
-be returned
-
-groups: is empty.
-
-mess_type: set to the message type field the application sent with the
-original message, this is only a short int (16bits). This value is
-already endian corrected before the application receives it.
-
-endian_mismatch: set to the size, in bytes, of the data buffers needed
-to completely receive this message and avoid a BUFFERS TOO SHORT
-error. This number is returned as a negative number. If the buffers
-were large enough a 0 will be returned.
-
-mess: is empty.
-
-So, when SP receive returns one of the *_TOO_SHORT errors you can
-examine the service type and mess type fields to get some information
-about what kind of message Spread is trying to give you. You can then
-examine the num groups and endian mismatch fields to discover how
-large your buffers need to be. You then increase your application
-buffers and call SP receive again. It should return with the message
-and without error (unless something else is also wrong).
-
-This retry approach is safe with multi-threaded applications because
-each call succeeds or fails on it's own and if two threads retry for
-the same message, one will get it and the other will get the message
-after it (which is what would happen anyway if they were not
-retrying).
-
-The retry approach does, however, require that the application check
-for errors when calling SP receive and if a *_TOO_SHORT error occurs
-they either enlarge their buffers or call SP receive again with the
-DROP_RECV flag set, as described below. If they either ignore errors
-or do not correct the short buffers, the application will continually
-loop calling SP receive and not receiving anything.
-
-If the application does not want to actually receive the entire data
-buffer or groups list, it has the option of calling SP_receive with
-the service type field set to the DROP_RECV flag. When this is done,
-Spread will treat the message just like most networking systems and
-return all the data and groups that will fit in the available space
-and truncate the rest. It will still return an error value informing
-the application that it has lost data. In simple applications or ones
-with relaxed, or specialized requirements this might be more useful
-then having to check for error values and retry the SP receive.
-
Deleted: trunk/daemon/license.txt
===================================================================
--- trunk/daemon/license.txt 2006-02-08 08:46:41 UTC (rev 289)
+++ trunk/daemon/license.txt 2006-02-08 09:11:18 UTC (rev 290)
@@ -1,68 +0,0 @@
-Spread Open-Source License -- Version 1.0
------------------------------------------
-Copyright (c) 1993-2001 Spread Concepts LLC. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following request and
- disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following request and
- disclaimer in the documentation and/or other materials provided
- with the distribution.
-
-3. All advertising materials (including web pages) mentioning features
- or use of this software, or software that uses this software, must
- display the following acknowledgment: "This product uses software
- developed by Spread Concepts LLC for use in the Spread toolkit. For
- more information about Spread see http://www.spread.org"
-
-4. The names "Spread" or "Spread toolkit" must not be used to endorse
- or promote products derived from this software without prior
- written permission.
-
-5. Redistributions of any form whatsoever must retain the following
- acknowledgment: "This product uses software developed by Spread
- Concepts LLC for use in the Spread toolkit. For more information about
- Spread, see http://www.spread.org"
-
-6. This license shall be governed by and construed and enforced in
- accordance with the laws of the State of Maryland, without
- reference to its conflicts of law provisions. The exclusive
- jurisdiction and venue for all legal actions relating to this
- license shall be in courts of competent subject matter jurisdiction
- located in the State of Maryland.
-
-TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, SPREAD IS PROVIDED
-UNDER THIS LICENSE ON AN AS IS BASIS, WITHOUT WARRANTY OF ANY KIND,
-EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES
-THAT SPREAD IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR
-PURPOSE OR NON-INFRINGING. ALL WARRANTIES ARE DISCLAIMED AND THE
-ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE CODE IS WITH
-YOU. SHOULD ANY CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE
-COPYRIGHT HOLDER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY
-NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY
-CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY CODE IS
-AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
-
-TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
-THE COPYRIGHT HOLDER OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY
-SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES FOR LOSS OF
-PROFITS, REVENUE, OR FOR LOSS OF INFORMATION OR ANY OTHER LOSS.
-
-YOU EXPRESSLY AGREE TO FOREVER INDEMNIFY, DEFEND AND HOLD HARMLESS THE
-COPYRIGHT HOLDERS AND CONTRIBUTORS OF SPREAD AGAINST ALL CLAIMS,
-DEMANDS, SUITS OR OTHER ACTIONS ARISING DIRECTLY OR INDIRECTLY FROM
-YOUR ACCEPTANCE AND USE OF SPREAD.
-
-Although NOT REQUIRED, we at Spread Concepts would appreciate it if
-active users of Spread put a link on their web site to Spread's web
-site when possible. We also encourage users to let us know who they
-are, how they are using Spread, and any comments they have through
-either e-mail (spread at spread.org) or our web site at
-(http://www.spread.org/comments).
-
Copied: trunk/docs/PORTING (from rev 281, trunk/daemon/PORTING)
Copied: trunk/docs/Short_Buffer_Handling.txt (from rev 281, trunk/daemon/Short_Buffer_Handling.txt)
Copied: trunk/license.txt (from rev 281, trunk/daemon/license.txt)
More information about the Spread-cvs
mailing list