Trivial changes, mostly to clean up diff noise. Majority of changes are comment corrections or licenseinfo updates. (does not include newview directory)
This commit is contained in:
Shyotl
@@ -2,31 +2,25 @@
|
||||
* @file llsd.h
|
||||
* @brief LLSD flexible data system.
|
||||
*
|
||||
* $LicenseInfo:firstyear=2005&license=viewergpl$
|
||||
*
|
||||
* Copyright (c) 2005-2009, Linden Research, Inc.
|
||||
*
|
||||
* $LicenseInfo:firstyear=2005&license=viewerlgpl$
|
||||
* Second Life Viewer Source Code
|
||||
* The source code in this file ("Source Code") is provided by Linden Lab
|
||||
* to you under the terms of the GNU General Public License, version 2.0
|
||||
* ("GPL"), unless you have obtained a separate licensing agreement
|
||||
* ("Other License"), formally executed by you and Linden Lab. Terms of
|
||||
* the GPL can be found in doc/GPL-license.txt in this distribution, or
|
||||
* online at http://secondlifegrid.net/programs/open_source/licensing/gplv2
|
||||
* Copyright (C) 2010, Linden Research, Inc.
|
||||
*
|
||||
* There are special exceptions to the terms and conditions of the GPL as
|
||||
* it is applied to this Source Code. View the full text of the exception
|
||||
* in the file doc/FLOSS-exception.txt in this software distribution, or
|
||||
* online at
|
||||
* http://secondlifegrid.net/programs/open_source/licensing/flossexception
|
||||
* This library is free software; you can redistribute it and/or
|
||||
* modify it under the terms of the GNU Lesser General Public
|
||||
* License as published by the Free Software Foundation;
|
||||
* version 2.1 of the License only.
|
||||
*
|
||||
* By copying, modifying or distributing this software, you acknowledge
|
||||
* that you have read and understood your obligations described above,
|
||||
* and agree to abide by those obligations.
|
||||
* This library is distributed in the hope that it will be useful,
|
||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
* Lesser General Public License for more details.
|
||||
*
|
||||
* ALL LINDEN LAB SOURCE CODE IS PROVIDED "AS IS." LINDEN LAB MAKES NO
|
||||
* WARRANTIES, EXPRESS, IMPLIED OR OTHERWISE, REGARDING ITS ACCURACY,
|
||||
* COMPLETENESS OR PERFORMANCE.
|
||||
* You should have received a copy of the GNU Lesser General Public
|
||||
* License along with this library; if not, write to the Free Software
|
||||
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
||||
*
|
||||
* Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA
|
||||
* $/LicenseInfo$
|
||||
*/
|
||||
|
||||
@@ -46,10 +40,10 @@
|
||||
/**
|
||||
LLSD provides a flexible data system similar to the data facilities of
|
||||
dynamic languages like Perl and Python. It is created to support exchange
|
||||
of structured data between loosly coupled systems. (Here, "loosly coupled"
|
||||
of structured data between loosely coupled systems. (Here, "loosely coupled"
|
||||
means not compiled together into the same module.)
|
||||
|
||||
Data in such exchanges must be highly tollerant of changes on either side
|
||||
Data in such exchanges must be highly tolerant of changes on either side
|
||||
such as:
|
||||
- recompilation
|
||||
- implementation in a different langauge
|
||||
@@ -57,19 +51,19 @@
|
||||
- execution of older versions (with fewer parameters)
|
||||
|
||||
To this aim, the C++ API of LLSD strives to be very easy to use, and to
|
||||
default to "the right thing" whereever possible. It is extremely tollerant
|
||||
default to "the right thing" wherever possible. It is extremely tolerant
|
||||
of errors and unexpected situations.
|
||||
|
||||
The fundimental class is LLSD. LLSD is a value holding object. It holds
|
||||
The fundamental class is LLSD. LLSD is a value holding object. It holds
|
||||
one value that is either undefined, one of the scalar types, or a map or an
|
||||
array. LLSD objects have value semantics (copying them copies the value,
|
||||
though it can be considered efficient, due to shareing.), and mutable.
|
||||
though it can be considered efficient, due to sharing), and mutable.
|
||||
|
||||
Undefined is the singular value given to LLSD objects that are not
|
||||
initialized with any data. It is also used as the return value for
|
||||
operations that return an LLSD,
|
||||
operations that return an LLSD.
|
||||
|
||||
The sclar data types are:
|
||||
The scalar data types are:
|
||||
- Boolean - true or false
|
||||
- Integer - a 32 bit signed integer
|
||||
- Real - a 64 IEEE 754 floating point value
|
||||
@@ -86,9 +80,73 @@
|
||||
|
||||
An array is a sequence of zero or more LLSD values.
|
||||
|
||||
Thread Safety
|
||||
|
||||
In general, these LLSD classes offer *less* safety than STL container
|
||||
classes. Implementations prior to this one were unsafe even when
|
||||
completely unrelated LLSD trees were in two threads due to reference
|
||||
sharing of special 'undefined' values that participated in the reference
|
||||
counting mechanism.
|
||||
|
||||
The dereference-before-refcount and aggressive tree sharing also make
|
||||
it impractical to share an LLSD across threads. A strategy of passing
|
||||
ownership or a copy to another thread is still difficult due to a lack
|
||||
of a cloning interface but it can be done with some care.
|
||||
|
||||
One way of transferring ownership is as follows:
|
||||
|
||||
void method(const LLSD input) {
|
||||
...
|
||||
LLSD * xfer_tree = new LLSD();
|
||||
{
|
||||
// Top-level values
|
||||
(* xfer_tree)['label'] = "Some text";
|
||||
(* xfer_tree)['mode'] = APP_MODE_CONSTANT;
|
||||
|
||||
// There will be a second-level
|
||||
LLSD subtree(LLSD::emptyMap());
|
||||
(* xfer_tree)['subtree'] = subtree;
|
||||
|
||||
// Do *not* copy from LLSD objects via LLSD
|
||||
// intermediaries. Only use plain-old-data
|
||||
// types as intermediaries to prevent reference
|
||||
// sharing.
|
||||
subtree['value1'] = input['value1'].asInteger();
|
||||
subtree['value2'] = input['value2'].asString();
|
||||
|
||||
// Close scope and drop 'subtree's reference.
|
||||
// Only xfer_tree has a reference to the second
|
||||
// level data.
|
||||
}
|
||||
...
|
||||
// Transfer the LLSD pointer to another thread. Ownership
|
||||
// transfers, this thread no longer has a reference to any
|
||||
// part of the xfer_tree and there's nothing to free or
|
||||
// release here. Receiving thread does need to delete the
|
||||
// pointer when it is done with the LLSD. Transfer
|
||||
// mechanism must perform correct data ordering operations
|
||||
// as dictated by architecture.
|
||||
other_thread.sendMessageAndPointer("Take This", xfer_tree);
|
||||
xfer_tree = NULL;
|
||||
|
||||
|
||||
Avoid this pattern which provides half of a race condition:
|
||||
|
||||
void method(const LLSD input) {
|
||||
...
|
||||
LLSD xfer_tree(LLSD::emptyMap());
|
||||
xfer_tree['label'] = "Some text";
|
||||
xfer_tree['mode'] = APP_MODE_CONSTANT;
|
||||
...
|
||||
other_thread.sendMessageAndPointer("Take This", xfer_tree);
|
||||
|
||||
|
||||
@nosubgrouping
|
||||
*/
|
||||
|
||||
// Normally undefined, used for diagnostics
|
||||
//#define LLSD_DEBUG_INFO 1
|
||||
|
||||
class LL_COMMON_API LLSD
|
||||
{
|
||||
public:
|
||||
@@ -211,7 +269,7 @@ public:
|
||||
//@}
|
||||
|
||||
/** @name Character Pointer Helpers
|
||||
These are helper routines to make working with char* the same as easy as
|
||||
These are helper routines to make working with char* as easy as
|
||||
working with strings.
|
||||
*/
|
||||
//@{
|
||||
@@ -275,7 +333,7 @@ public:
|
||||
/** @name Type Testing */
|
||||
//@{
|
||||
enum Type {
|
||||
TypeUndefined,
|
||||
TypeUndefined = 0,
|
||||
TypeBoolean,
|
||||
TypeInteger,
|
||||
TypeReal,
|
||||
@@ -285,7 +343,10 @@ public:
|
||||
TypeURI,
|
||||
TypeBinary,
|
||||
TypeMap,
|
||||
TypeArray
|
||||
TypeArray,
|
||||
TypeLLSDTypeEnd,
|
||||
TypeLLSDTypeBegin = TypeUndefined,
|
||||
TypeLLSDNumTypes = (TypeLLSDTypeEnd - TypeLLSDTypeBegin)
|
||||
};
|
||||
|
||||
Type type() const;
|
||||
@@ -311,7 +372,7 @@ public:
|
||||
If you get a linker error about these being missing, you have made
|
||||
mistake in your code. DO NOT IMPLEMENT THESE FUNCTIONS as a fix.
|
||||
|
||||
All of thse problems stem from trying to support char* in LLSD or in
|
||||
All of these problems stem from trying to support char* in LLSD or in
|
||||
std::string. There are too many automatic casts that will lead to
|
||||
using an arbitrary pointer or scalar type to std::string.
|
||||
*/
|
||||
@@ -320,7 +381,7 @@ public:
|
||||
void assign(const void*); ///< assign from arbitrary pointers
|
||||
LLSD& operator=(const void*); ///< assign from arbitrary pointers
|
||||
|
||||
bool has(Integer) const; ///< has only works for Maps
|
||||
bool has(Integer) const; ///< has() only works for Maps
|
||||
//@}
|
||||
|
||||
/** @name Implementation */
|
||||
@@ -395,8 +456,8 @@ struct llsd_select_string : public std::unary_function<LLSD, LLSD::String>
|
||||
LL_COMMON_API std::ostream& operator<<(std::ostream& s, const LLSD& llsd);
|
||||
|
||||
/** QUESTIONS & TO DOS
|
||||
- Would Binary be more convenient as usigned char* buffer semantics?
|
||||
- Should Binary be convertable to/from String, and if so how?
|
||||
- Would Binary be more convenient as unsigned char* buffer semantics?
|
||||
- Should Binary be convertible to/from String, and if so how?
|
||||
- as UTF8 encoded strings (making not like UUID<->String)
|
||||
- as Base64 or Base96 encoded (making like UUID<->String)
|
||||
- Conversions to std::string and LLUUID do not result in easy assignment
|
||||
|
||||
Reference in New Issue
Block a user