Package hashring implements consistent hashing hashring data structure. In general, consistent hashing is all about mapping of object from a very big set of values (e.g. request id) to object from a quite small set (e.g. server address). The word "consistent" means that it can produce consistent mapping on different machines or processes without additional state exchange and communication. For more theory about the subject please see this great document: https://theory.stanford.edu/~tim/s16/l/l1.pdf There are two goals for this hashring implementation: 1) To be efficient in highly concurrent applications by blocking read operations for the least possible time. 2) To correctly handle very rare but yet possible hash collisions, which may break all your eventually consistent application. To reach the first goal hashring uses immutable AVL tree internally, making read operations (getting item for object) blocked only for a tiny amount of time needed to swap the ring's tree root after some write operation (insertion or deletion). The second goal is reached by using ring of size 2^64-1 points, which dramatically reduces the probability of hash collisions (the greater the number of items on the ring, the higher the probability of collisions) and implementation that covers collisions.
Package pcre provides access to the Perl Compatible Regular Expresion library, PCRE. It implements two main types, Regexp and Matcher. Regexp objects store a compiled regular expression. They consist of two immutable parts: pcre and pcre_extra. Compile()/MustCompile() initialize pcre. Calling Study() on a compiled Regexp initializes pcre_extra. Compilation of regular expressions using Compile or MustCompile is slightly expensive, so these objects should be kept and reused, instead of compiling them from scratch for each matching attempt. CompileJIT and MustCompileJIT are way more expensive, because they run Study() after compiling a Regexp, but they tend to give much better perfomance: http://sljit.sourceforge.net/regex_perf.html Matcher objects keeps the results of a match against a []byte or string subject. The Group and GroupString functions provide access to capture groups; both versions work no matter if the subject was a []byte or string, but the version with the matching type is slightly more efficient. Matcher objects contain some temporary space and refer the original subject. They are mutable and can be reused (using Match, MatchString, Reset or ResetString). For details on the regular expression language implemented by this package and the flags defined below, see the PCRE documentation. http://www.pcre.org/pcre.txt
Package bullseye provides an implementation of a DataFrame using Apache Arrow. The DataFrame is an immutable heterogeneous tabular data structure with labeled columns. It stores it's raw bytes using a provided Arrow Allocator by using the fundamental data structure of Array (columns), which holds a sequence of values of the same type. An array consists of memory holding the data and an additional validity bitmap that indicates if the corresponding entry in the array is valid (not null). Any DataFrames created should be released using Release() to decrement the reference and free up the memory managed by the Arrow implementation. Look in the dataframe package to get started.
datalark makes IPLD data legible to, and constructable in, starlark. Given an IPLD Schema (and optionally, a list of types to focus on), datalark can generate a set of starlark constructor functions for those types. These functions should generally DWIM ("do what I mean"): for structs, they accept kwargs corresponding to the field names, etc. Some functions get clever: for example, for structs with stringy representations (stringjoin, etc), the representation form can be used as an argument to the constructor instead of the kwargs form, and the construction will "DWIM" with that information and parse it in the appropriate way. Standard datamodel data is also always legible, and a set of functions for creating it can also be obtained from the datalark package. All IPLD data exposed to starlark always acts as if it is "frozen", in starlark parlance. This should be unsurprising, since IPLD is already oriented around immutability. datalark can be used on natural golang structs by combining it with the go-ipld-prime/node/bindnode package. This may make it an interesting alternative to github.com/starlight-go/starlight (although admittedly more complicated; it's probably only worth it if you also already value some of the features of IPLD Schemas). Future objectives for this package include the ability to provide a function to starlark which will accept an IPLD Schema document and a type name as parameters, and will return a constructor for that type. (Not yet implemented.)
Package intern implements fast, immutable string interning. The package is a cgo binding for libintern: Interning is a way of storing distinct strings only once in memory: Each string is assigned an ID of type uint32. IDs start at 1 and increment towards 2^32-1: Two-way lookup is provided: The package also provides a way to iterate unique strings in order of ID, optimize string repositories using frequency analysis, and restore string repositories to a previous snapshot. This package is *NOT* safe to use from multiple goroutines without locking, e.g. https://golang.org/pkg/sync/#Mutex
Package web is a minimal web middleware toolkit build upon build upon the Go 1.7 immutable context(https://golang.org/pkg/context).
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package listy provides functional programming idioms for Go slices. The list of functions is inspired by a subset of the Data.List package from Haskell, and similar libraries seen in other languages. The emphasis of this library is on expressiveness and clarity. With one exception (`Swap`, for `Sort.Interface`), methods treat inputs as immutable, returning copies rather than mutating slices in place.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package iavl implements a versioned, snapshottable (immutable) AVL+ tree for persisting key-value pairs. Basic usage of MutableTree. Proof of existence: Proof of absence: Now we delete an old version: Can't create a proof of absence for a version we no longer have:
Package gkvlite provides a simple, ordered, ACID, key-value persistence library. It provides persistent, immutable data structure abstrations.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package gopath implements an alternative API to Go's path processing libraries. It implements the recommondations from the article https://blog.golang.org/errors-are-values. For even more information, also have a look at the article http://blog.golang.org/error-handling-and-go. What's special to gopath is its ability to write code that processes paths in a fluent way, while doing the error handling later. This is possible by using the immutable object gopath.GoPath, which either represents a path, or an error. All operations on an errorneous GoPath are no-ops, therefore the first error ever occured in a chain of operations will remain visible. This way, you can work with GoPaths like you would with any other object.
Package iavl implements a versioned, snapshottable (immutable) AVL+ tree for persisting key-value pairs. Basic usage of MutableTree. Proof of existence: Proof of absence: Now we delete an old version: Can't create a proof of absence for a version we no longer have:
Package moss stands for "memory-oriented sorted segments", and provides a data structure that manages an ordered Collection of key-val entries, with optional persistence. The design is similar to a simplified LSM tree (log structured merge tree), but is more like a "LSM array", in that a stack of immutable, sorted key-val arrays or "segments" is maintained. When there's an incoming Batch of key-val mutations (see: ExecuteBatch()), the Batch, which is an array of key-val mutations, is sorted in-place and becomes an immutable "segment". Then, the segment is atomically pushed onto a stack of segment pointers. A higher segment in the stack will shadow mutations of the same key from lower segments. Separately, an asynchronous goroutine (the "merger") will continuously merge N sorted segments to keep stack height low. In the best case, a remaining, single, large sorted segment will be efficient in memory usage and efficient for binary search and range iteration. Iterations when the stack height is > 1 are implementing using a N-way heap merge. A Batch and a segment is actually two arrays: a byte array of contiguous key-val entries; and an uint64 array of entry offsets and key-val lengths that refer to the previous key-val entries byte array. In this design, stacks are treated as immutable via a copy-on-write approach whenever a stack is "modified". So, readers and writers essentially don't block each other, and taking a Snapshot is also a relatively simple operation of atomically cloning the stack of segment pointers. Of note: mutations are only supported through Batch operations, which acknowledges the common practice of using batching to achieve higher write performance and embraces it. Additionally, higher performance can be attained by using the batch memory pre-allocation parameters and the Batch.Alloc() API, allowing applications to serialize keys and vals directly into memory maintained by a batch, which can avoid extra memory copying. IMPORTANT: The keys in a Batch must be unique. That is, myBatch.Set("x", "foo"); myBatch.Set("x", "bar") is not supported. Applications that do not naturally meet this requirement might maintain their own map[key]val data structures to ensure this uniqueness constraint. An optional, asynchronous persistence goroutine (the "persister") can drain mutations to a lower level, ordered key-value storage layer. An optional, built-in storage layer ("mossStore") is available, that will asynchronously write segments to the end of a file (append only design), with reads performed using mmap(), and with user controllable compaction configuration. See: OpenStoreCollection(). NOTE: the mossStore persistence design does not currently support moving files created on one machine endian'ness type to another machine with a different endian'ness type.
Package fragbag provides interfaces for using fragment libraries along with several implementations of fragment libraries. This package makes it possible for clients to define their own fragment libraries while reusing all of the infrastructure which operates on fragment libraries. The central type of this package is the Library interface, along with its child interfaces: SequenceLibrary, StructureLibrary and WeightedLibrary. The Library interface states that all libraries have names, some collection of fragments of uniform size, possibly a sub library and a uniquely identifying tag. The tag is used to recapitulate the type of the fragment library (from the Openers map) when reading them from disk. Libraries may also wrap other libraries to provide additional functionality. For example, the WeightedLibrary interface describes any fragment library that can weight the raw frequency of a fragment against a query. But this functionality can be added to existing libraries by wrapping them with additional information. (For example, see the implementation of the WeightedTfIdf library.) A central design decision of this package is that all fragment libraries are immutable. Once they are created, they cannot be changed. Therefore, all actions defined by the Library interfaces never mutate an existing library.
Package iavl implements a versioned, snapshottable (immutable) AVL+ tree for persisting key-value pairs. Basic usage of MutableTree. Proof of existence: Proof of absence: Now we delete an old version: Can't create a proof of absence for a version we no longer have:
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122. Copyright (C) 2011 by Krzysztof Kowalik <chris@nu7hat.ch>
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122. Copyright (C) 2011 by Krzysztof Kowalik <chris@nu7hat.ch>
Package pcre provides access to the Perl Compatible Regular Expresion library, PCRE. It implements two main types, Regexp and Matcher. Regexp objects store a compiled regular expression. They consist of two immutable parts: pcre and pcre_extra. Compile()/MustCompile() initialize pcre. Calling Study() on a compiled Regexp initializes pcre_extra. Compilation of regular expressions using Compile or MustCompile is slightly expensive, so these objects should be kept and reused, instead of compiling them from scratch for each matching attempt. CompileJIT and MustCompileJIT are way more expensive, because they run Study() after compiling a Regexp, but they tend to give much better perfomance: http://sljit.sourceforge.net/regex_perf.html Matcher objects keeps the results of a match against a []byte or string subject. The Group and GroupString functions provide access to capture groups; both versions work no matter if the subject was a []byte or string, but the version with the matching type is slightly more efficient. Matcher objects contain some temporary space and refer the original subject. They are mutable and can be reused (using Match, MatchString, Reset or ResetString). For details on the regular expression language implemented by this package and the flags defined below, see the PCRE documentation. http://www.pcre.org/pcre.txt
Package netaddr contains a IP address type that's in many ways better than the Go standard library's net.IP type. Building on that IP type, the package also contains IPPrefix, IPPort, IPRange, and IPSet types. Notably, this package's IP type takes less memory, is immutable, comparable (supports == and being a map key), and more. See https://github.com/inetaf/netaddr for background.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package errors provides a simple API for creating and handling errors which are identified by codes. Many times, a library, service, or any other kind of implementation needs to deal with third party packages and it may need to identify errors for: 1. Perform some operation before returning it to the caller, for example doing some kind of rollback operations. 2. Localize the error. Meanwhile those 2 needs could be implemented with error values (defining them as global variables of the package) or specific types, both of them aren't ideal because: 1. Package variables values cannot be modified on each error instance, so they cannot to be endowed with specific information which is useful for the developers and operations teams for identifying the source of the problem. 2. Package variables aren't immutable, so their values, although unlikely, could be erroneous overridden. 3. Specific types don't have the 2 previous problems, however when a considerable list of different errors is needed, quite a few boilerplate is required for creating them and the package documentation gets polluted. 4. Specific types must implement the same behavior over and over or use a base type which must be embedded in all the types to have the same logic. This could be fine in single package, but when you want to have the same mechanism on a bunch of packages (think in medium/large implementations done by any company whose code base is written in Go) is less than desirable to spread between teams. 5. When using any of them and the errors are transmitted over the wire (this problem arises when the dependency is a remote service), then the client must identify those errors in order to reconstruct the error to use the same value (when using package variables) or type (when using specific types) for allowing the caller to be able to identify the error. The 2 mentioned issues can be solved by errors which are identified by codes and without the need of using package variables nor specific error types, just using a minimal and simple public API exposed by this package. Nonetheless this package doesn't attempt to fit to all the use cases, it fits to several of the uses cases which were found in my experience, but they are not all. Hence, before using it, assess if it can bring the mentioned benefits to your implementation (for example a minimal library may have enough just returning standard errors or using a couple of package variables error values variables or specific types). Errors are for users, but they must be useful for operations, too. In order to achieve both, the error type of this package is endowed with several information. 1. A code and a static message. Both information is useful for users and operations, because each code should be quite specific and self descriptive for providing a synthesized information about the error which has happened. Having a specific error code is also good to have each error properly documented, so it can provide more detailed information about the error when its synthesized information isn't enough. 2. An unique ID. Each error instance has an unique ID. For users, it's useful because they could report it to the support team, a part of the code. Such ID could be helpful to provide a customized feedback/response when needed and for the operations team, could use the ID to correlate errors, when they are registered/tracked in different operational systems or, for any reason, in the same one several times. 3. Metadata. Despite that the code, and its associated message, should be precise, the operations team needs more information about what happened when the error has happened in some circumstances which aren't clear, for example the input parameter values, variable values, etc. Developers should have a way to provide such important context information when creating the errors and that's what, in this package, is called metadata. 4. The call stack. Call stacks are ugly, but they provide the trace where the error was originated and such information is very useful for the operations team and maintainers, when the error has happened in unclear circumstances. 5. Original error. The most of the times, third party packages are used and, obviously, those package don't probably use errors created by this package, hence they don't have all the information, or a lest in the same way. Your implementation has committed to return error with codes, but the original error must be preserved because it may have additional information which may be useful for the operations team and maintainers. In summary, from the point of view of users, the error should be precise and concise, without having any useless information and avoiding to leak important information about the system; on the other hand, the operations team and maintainers need much more information about the errors in order of being able to understand the cause of the error. This package doesn't intentionally export the error type, because: 1. Functions' signatures, which return errors, should always return a standard error. 2. Type assertion for finding out errors information is less than ideal in comparison on having an API. Hence, this package export some functions to get information about the error, however it only intentionally allows to get a part of it, because the information destined for operations is only thought to be exposed through systems for such purpose, for example logging. The error values returned by this package can be printed with more or less information depending used verb and flags. Below you can see all the verbs and flags and the information that each one prints, any other verb, it prints nothing. Therefore, developers should consider to use one another depending the needs and the audience of those messages.
Package datastore provides a client for Google Cloud Datastore. See https://godoc.org/cloud.google.com/go for authentication, timeouts, connection pooling and similar aspects of this package. Entities are the unit of storage and are associated with a key. A key consists of an optional parent key, a string application ID, a string kind (also known as an entity type), and either a StringID or an IntID. A StringID is also known as an entity name or key name. It is valid to create a key with a zero StringID and a zero IntID; this is called an incomplete key, and does not refer to any saved entity. Putting an entity into the datastore under an incomplete key will cause a unique key to be generated for that entity, with a non-zero IntID. An entity's contents are a mapping from case-sensitive field names to values. Valid value types are: Slices of structs are valid, as are structs that contain slices. The Get and Put functions load and save an entity's contents. An entity's contents are typically represented by a struct pointer. Example code: GetMulti, PutMulti and DeleteMulti are batch versions of the Get, Put and Delete functions. They take a []*Key instead of a *Key, and may return a datastore.MultiError when encountering partial failure. Mutate generalizes PutMulti and DeleteMulti to a sequence of any Datastore mutations. It takes a series of mutations created with NewInsert, NewUpdate, NewUpsert and NewDelete and applies them atomically. An entity's contents can be represented by a variety of types. These are typically struct pointers, but can also be any type that implements the PropertyLoadSaver interface. If using a struct pointer, you do not have to explicitly implement the PropertyLoadSaver interface; the datastore will automatically convert via reflection. If a struct pointer does implement PropertyLoadSaver then those methods will be used in preference to the default behavior for struct pointers. Struct pointers are more strongly typed and are easier to use; PropertyLoadSavers are more flexible. The actual types passed do not have to match between Get and Put calls or even across different calls to datastore. It is valid to put a *PropertyList and get that same entity as a *myStruct, or put a *myStruct0 and get a *myStruct1. Conceptually, any entity is saved as a sequence of properties, and is loaded into the destination value on a property-by-property basis. When loading into a struct pointer, an entity that cannot be completely represented (such as a missing field) will result in an ErrFieldMismatch error but it is up to the caller whether this error is fatal, recoverable or ignorable. By default, for struct pointers, all properties are potentially indexed, and the property name is the same as the field name (and hence must start with an upper case letter). Fields may have a `datastore:"name,options"` tag. The tag name is the property name, which must be one or more valid Go identifiers joined by ".", but may start with a lower case letter. An empty tag name means to just use the field name. A "-" tag name means that the datastore will ignore that field. The only valid options are "omitempty", "noindex" and "flatten". If the options include "omitempty" and the value of the field is a zero value, then the field will be omitted on Save. Zero values are best defined in the golang spec (https://golang.org/ref/spec#The_zero_value). Struct field values will never be empty, except for nil pointers. If options include "noindex" then the field will not be indexed. All fields are indexed by default. Strings or byte slices longer than 1500 bytes cannot be indexed; fields used to store long strings and byte slices must be tagged with "noindex" or they will cause Put operations to fail. For a nested struct field, the options may also include "flatten". This indicates that the immediate fields and any nested substruct fields of the nested struct should be flattened. See below for examples. To use multiple options together, separate them by a comma. The order does not matter. If the options is "" then the comma may be omitted. Example code: A field of slice type corresponds to a Datastore array property, except for []byte, which corresponds to a Datastore blob. Zero-length slice fields are not saved. Slice fields of length 1 or greater are saved as Datastore arrays. When a zero-length Datastore array is loaded into a slice field, the slice field remains unchanged. If a non-array value is loaded into a slice field, the result will be a slice with one element, containing the value. Loading a Datastore Null into a basic type (int, float, etc.) results in a zero value. Loading a Null into a slice of basic type results in a slice of size 1 containing the zero value. Loading a Null into a pointer field results in nil. Loading a Null into a field of struct type is an error. A struct field can be a pointer to a signed integer, floating-point number, string or bool. Putting a non-nil pointer will store its dereferenced value. Putting a nil pointer will store a Datastore Null property, unless the field is marked omitempty, in which case no property will be stored. Loading a Null into a pointer field sets the pointer to nil. Loading any other value allocates new storage with the value, and sets the field to point to it. If the struct contains a *datastore.Key field tagged with the name "__key__", its value will be ignored on Put. When reading the Entity back into the Go struct, the field will be populated with the *datastore.Key value used to query for the Entity. Example code: If the struct pointed to contains other structs, then the nested or embedded structs are themselves saved as Entity values. For example, given these definitions: then an Outer would have one property, Inner, encoded as an Entity value. If an outer struct is tagged "noindex" then all of its implicit flattened fields are effectively "noindex". If the Inner struct contains a *Key field with the name "__key__", like so: then the value of K will be used as the Key for Inner, represented as an Entity value in datastore. If any nested struct fields should be flattened, instead of encoded as Entity values, the nested struct field should be tagged with the "flatten" option. For example, given the following: an Outer's properties would be equivalent to those of: Note that the "flatten" option cannot be used for Entity value fields. The server will reject any dotted field names for an Entity value. An entity's contents can also be represented by any type that implements the PropertyLoadSaver interface. This type may be a struct pointer, but it does not have to be. The datastore package will call Load when getting the entity's contents, and Save when putting the entity's contents. Possible uses include deriving non-stored fields, verifying fields, or indexing a field only if its value is positive. Example code: The *PropertyList type implements PropertyLoadSaver, and can therefore hold an arbitrary entity's contents. If a type implements the PropertyLoadSaver interface, it may also want to implement the KeyLoader interface. The KeyLoader interface exists to allow implementations of PropertyLoadSaver to also load an Entity's Key into the Go type. This type may be a struct pointer, but it does not have to be. The datastore package will call LoadKey when getting the entity's contents, after calling Load. Example code: To load a Key into a struct which does not implement the PropertyLoadSaver interface, see the "Key Field" section above. Queries retrieve entities based on their properties or key's ancestry. Running a query yields an iterator of results: either keys or (key, entity) pairs. Queries are re-usable and it is safe to call Query.Run from concurrent goroutines. Iterators are not safe for concurrent use. Queries are immutable, and are either created by calling NewQuery, or derived from an existing query by calling a method like Filter or Order that returns a new query value. A query is typically constructed by calling NewQuery followed by a chain of zero or more such methods. These methods are: Example code: Client.RunInTransaction runs a function in a transaction. Example code: Pass the ReadOnly option to RunInTransaction if your transaction is used only for Get, GetMulti or queries. Read-only transactions are more efficient. This package supports the Cloud Datastore emulator, which is useful for testing and development. Environment variables are used to indicate that datastore traffic should be directed to the emulator instead of the production Datastore service. To install and set up the emulator and its environment variables, see the documentation at https://cloud.google.com/datastore/docs/tools/datastore-emulator.
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122. Copyright (C) 2011 by Krzysztof Kowalik <chris@nu7hat.ch>
Package iavl implements a versioned, snapshottable (immutable) AVL+ tree for persisting key-value pairs. Basic usage of MutableTree. Proof of existence: Proof of absence: Now we delete an old version: Can't create a proof of absence for a version we no longer have:
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package dec is a Go wrapper around the decNumber library (arbitrary precision decimal arithmetic). For more information about the decNumber library, and detailed documentation, see http://speleotrove.com/decimal/dec.html It implements the General Decimal Arithmetic Specification in ANSI C. This specification defines a decimal arithmetic which meets the requirements of commercial, financial, and human-oriented applications. It also matches the decimal arithmetic in the IEEE 754 Standard for Floating Point Arithmetic. The library fully implements the specification, and hence supports integer, fixed-point, and floating-point decimal numbers directly, including infinite, NaN (Not a Number), and subnormal values. Both arbitrary-precision and fixed-size representations are supported. General usage notes: The Number format is optimized for efficient processing of relatively short numbers; It does, however, support arbitrary precision (up to 999,999,999 digits) and arbitrary exponent range (Emax in the range 0 through 999,999,999 and Emin in the range -999,999,999 through 0). Mathematical functions (for example Exp()) as identified below are restricted more tightly: digits, emax, and -emin in the context must be <= MaxMath (999999), and their operand(s) must be within these bounds. Logical functions are further restricted; their operands must be finite, positive, have an exponent of zero, and all digits must be either 0 or 1. The result will only contain digits which are 0 or 1 (and will have exponent=0 and a sign of 0). Operands to operator functions are never modified unless they are also specified to be the result number (which is always permitted). Other than that case, operands must not overlap. Go implementation details: The decimal32, decimal64 and decimal128 types are merged into Single, Double and Quad, respectively. Contexts are created with a immutable precision (i.e. number of digits). If one needs to change precision on the fly, discard the existing context and create a new one with the required precision. From a programming standpoint, any initialized Number is a valid operand in arithmetic operations, regardless of the settings or existence of its creator Context (not to be confused with having a valid value in a given arithmetic operation). Arithmetic functions are Number methods. The value of the receiver of the method will be set to the result of the operation. For example: Arithmetic methods always return the receiver in order to allow chain calling: Using the same Number as operand and result, like in n.Multiply(n, n, ctx), is legal and will not produce unexpected results. A few functions like the context status manipulation functions have been moved to their own type (Status). The C call decContextTestStatus(ctx, mask) is therefore replaced by ctx.Status().Set(mask) in the Go implementation. The same goes for decNumberClassToString(number) which is repleaced by number.Class().String() in go. Error handling: although most arithmetic functions can cause errors, the standard Go error handling is not used in its idiomatic form. That is, arithmetic functions do not return errors. Instead, the type of the error is ORed into the status flags in the current context (Context type). It is the responsibility of the caller to clear the status flags as required. The result of any routine which returns a number will always be a valid number (which may be a special value, such as an Infinity or NaN). This permits the use of much fewer error checks; a single check for a whole computation is often enough. To check for errors, get the Context's status with the Status() function (see the Status type), or use the Context's ErrorStatus() function. The package provides facilities for managing free-lists of Numbers in order to relieve pressure on the garbage collector in computation intensive applications. NumberPool is in fact a simple wrapper around a *Context and a sync.Pool (or the lighter util.Pool provided in the util subpackage); NumberPool will automatically cast the return value of Get() to the desired type. For example: Note the use of pool.Context on the last statement. If a particular implementation needs always-initialized numbers (like any new Go variable being initialize to the 0 value of its type), the pool's New function can be set for example to: If an application needs to change its arithmetic precision on the fly, any NumberPool built on top of the affected Context's will need to be discarded and recreated along with the Context. This will not affect existing numbers that can still be used as valid operands in arithmetic functions. Go re-implementation of decNumber's example1.c - simple addition. Cnvert the first two argument words to decNumber, add them together, and display the result. Extended re-implementation of decNumber's example2.c - compound interest. With added error handling from example3.c. Go re-implementation of decNumber's example5.c. Compressed formats. Go re-implementation of decNumber's example6.c. Packed Decimal numbers. This example reworks Example 2, starting and ending with Packed Decimal numbers. Go re-implementation of decNumber's example7.c. Using decQuad to add two numbers together. Go re-implementation of decNumber's example8.c. Using Quad with Number
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package datastore provides a client for Google Cloud Datastore. See https://godoc.org/cloud.google.com/go for authentication, timeouts, connection pooling and similar aspects of this package. Entities are the unit of storage and are associated with a key. A key consists of an optional parent key, a string application ID, a string kind (also known as an entity type), and either a StringID or an IntID. A StringID is also known as an entity name or key name. It is valid to create a key with a zero StringID and a zero IntID; this is called an incomplete key, and does not refer to any saved entity. Putting an entity into the datastore under an incomplete key will cause a unique key to be generated for that entity, with a non-zero IntID. An entity's contents are a mapping from case-sensitive field names to values. Valid value types are: Slices of structs are valid, as are structs that contain slices. The Get and Put functions load and save an entity's contents. An entity's contents are typically represented by a struct pointer. Example code: GetMulti, PutMulti and DeleteMulti are batch versions of the Get, Put and Delete functions. They take a []*Key instead of a *Key, and may return a datastore.MultiError when encountering partial failure. Mutate generalizes PutMulti and DeleteMulti to a sequence of any Datastore mutations. It takes a series of mutations created with NewInsert, NewUpdate, NewUpsert and NewDelete and applies them atomically. An entity's contents can be represented by a variety of types. These are typically struct pointers, but can also be any type that implements the PropertyLoadSaver interface. If using a struct pointer, you do not have to explicitly implement the PropertyLoadSaver interface; the datastore will automatically convert via reflection. If a struct pointer does implement PropertyLoadSaver then those methods will be used in preference to the default behavior for struct pointers. Struct pointers are more strongly typed and are easier to use; PropertyLoadSavers are more flexible. The actual types passed do not have to match between Get and Put calls or even across different calls to datastore. It is valid to put a *PropertyList and get that same entity as a *myStruct, or put a *myStruct0 and get a *myStruct1. Conceptually, any entity is saved as a sequence of properties, and is loaded into the destination value on a property-by-property basis. When loading into a struct pointer, an entity that cannot be completely represented (such as a missing field) will result in an ErrFieldMismatch error but it is up to the caller whether this error is fatal, recoverable or ignorable. By default, for struct pointers, all properties are potentially indexed, and the property name is the same as the field name (and hence must start with an upper case letter). Fields may have a `datastore:"name,options"` tag. The tag name is the property name, which must be one or more valid Go identifiers joined by ".", but may start with a lower case letter. An empty tag name means to just use the field name. A "-" tag name means that the datastore will ignore that field. The only valid options are "omitempty", "noindex" and "flatten". If the options include "omitempty" and the value of the field is a zero value, then the field will be omitted on Save. Zero values are best defined in the golang spec (https://golang.org/ref/spec#The_zero_value). Struct field values will never be empty, except for nil pointers. If options include "noindex" then the field will not be indexed. All fields are indexed by default. Strings or byte slices longer than 1500 bytes cannot be indexed; fields used to store long strings and byte slices must be tagged with "noindex" or they will cause Put operations to fail. For a nested struct field, the options may also include "flatten". This indicates that the immediate fields and any nested substruct fields of the nested struct should be flattened. See below for examples. To use multiple options together, separate them by a comma. The order does not matter. If the options is "" then the comma may be omitted. Example code: A field of slice type corresponds to a Datastore array property, except for []byte, which corresponds to a Datastore blob. Zero-length slice fields are not saved. Slice fields of length 1 or greater are saved as Datastore arrays. When a zero-length Datastore array is loaded into a slice field, the slice field remains unchanged. If a non-array value is loaded into a slice field, the result will be a slice with one element, containing the value. Loading a Datastore Null into a basic type (int, float, etc.) results in a zero value. Loading a Null into a slice of basic type results in a slice of size 1 containing the zero value. Loading a Null into a pointer field results in nil. Loading a Null into a field of struct type is an error. A struct field can be a pointer to a signed integer, floating-point number, string or bool. Putting a non-nil pointer will store its dereferenced value. Putting a nil pointer will store a Datastore Null property, unless the field is marked omitempty, in which case no property will be stored. Loading a Null into a pointer field sets the pointer to nil. Loading any other value allocates new storage with the value, and sets the field to point to it. If the struct contains a *datastore.Key field tagged with the name "__key__", its value will be ignored on Put. When reading the Entity back into the Go struct, the field will be populated with the *datastore.Key value used to query for the Entity. Example code: If the struct pointed to contains other structs, then the nested or embedded structs are themselves saved as Entity values. For example, given these definitions: then an Outer would have one property, Inner, encoded as an Entity value. If an outer struct is tagged "noindex" then all of its implicit flattened fields are effectively "noindex". If the Inner struct contains a *Key field with the name "__key__", like so: then the value of K will be used as the Key for Inner, represented as an Entity value in datastore. If any nested struct fields should be flattened, instead of encoded as Entity values, the nested struct field should be tagged with the "flatten" option. For example, given the following: an Outer's properties would be equivalent to those of: Note that the "flatten" option cannot be used for Entity value fields. The server will reject any dotted field names for an Entity value. An entity's contents can also be represented by any type that implements the PropertyLoadSaver interface. This type may be a struct pointer, but it does not have to be. The datastore package will call Load when getting the entity's contents, and Save when putting the entity's contents. Possible uses include deriving non-stored fields, verifying fields, or indexing a field only if its value is positive. Example code: The *PropertyList type implements PropertyLoadSaver, and can therefore hold an arbitrary entity's contents. If a type implements the PropertyLoadSaver interface, it may also want to implement the KeyLoader interface. The KeyLoader interface exists to allow implementations of PropertyLoadSaver to also load an Entity's Key into the Go type. This type may be a struct pointer, but it does not have to be. The datastore package will call LoadKey when getting the entity's contents, after calling Load. Example code: To load a Key into a struct which does not implement the PropertyLoadSaver interface, see the "Key Field" section above. Queries retrieve entities based on their properties or key's ancestry. Running a query yields an iterator of results: either keys or (key, entity) pairs. Queries are re-usable and it is safe to call Query.Run from concurrent goroutines. Iterators are not safe for concurrent use. Queries are immutable, and are either created by calling NewQuery, or derived from an existing query by calling a method like Filter or Order that returns a new query value. A query is typically constructed by calling NewQuery followed by a chain of zero or more such methods. These methods are: Example code: Client.RunInTransaction runs a function in a transaction. Example code: Pass the ReadOnly option to RunInTransaction if your transaction is used only for Get, GetMulti or queries. Read-only transactions are more efficient. This package supports the Cloud Datastore emulator, which is useful for testing and development. Environment variables are used to indicate that datastore traffic should be directed to the emulator instead of the production Datastore service. To install and set up the emulator and its environment variables, see the documentation at https://cloud.google.com/datastore/docs/tools/datastore-emulator.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122. Copyright (C) 2011 by Krzysztof Kowalik <chris@nu7hat.ch>
Package cbor is a modern CBOR codec (RFC 8949 & RFC 7049) with CBOR tags, Go struct tags (toarray/keyasint/omitempty), Core Deterministic Encoding, CTAP2, Canonical CBOR, float64->32->16, and duplicate map key detection. Encoding options allow "preferred serialization" by encoding integers and floats to their smallest forms (e.g. float16) when values fit. Struct tags like "keyasint", "toarray" and "omitempty" make CBOR data smaller and easier to use with structs. For example, "toarray" tag makes struct fields encode to CBOR array elements. And "keyasint" makes a field encode to an element of CBOR map with specified int key. Latest docs can be viewed at https://github.com/fxamacker/cbor#cbor-library-in-go The Quick Start guide is at https://github.com/fxamacker/cbor#quick-start Function signatures identical to encoding/json include: Standard interfaces include: Custom encoding and decoding is possible by implementing standard interfaces for user-defined Go types. Codec functions are available at package-level (using defaults options) or by creating modes from options at runtime. "Mode" in this API means definite way of encoding (EncMode) or decoding (DecMode). EncMode and DecMode interfaces are created from EncOptions or DecOptions structs. Modes use immutable options to avoid side-effects and simplify concurrency. Behavior of modes won't accidentally change at runtime after they're created. Modes are intended to be reused and are safe for concurrent use. EncMode and DecMode Interfaces Using Default Encoding Mode Using Default Decoding Mode Creating and Using Encoding Modes Predefined Encoding Options: https://github.com/fxamacker/cbor#predefined-encoding-options Encoding Options: https://github.com/fxamacker/cbor#encoding-options Decoding Options: https://github.com/fxamacker/cbor#decoding-options Struct tags like `cbor:"name,omitempty"` and `json:"name,omitempty"` work as expected. If both struct tags are specified then `cbor` is used. Struct tags like "keyasint", "toarray", and "omitempty" make it easy to use very compact formats like COSE and CWT (CBOR Web Tokens) with structs. For example, "toarray" makes struct fields encode to array elements. And "keyasint" makes struct fields encode to elements of CBOR map with int keys. https://raw.githubusercontent.com/fxamacker/images/master/cbor/v2.0.0/cbor_easy_api.png Struct tags are listed at https://github.com/fxamacker/cbor#struct-tags-1 Over 375 tests are included in this package. Cover-guided fuzzing is handled by fxamacker/cbor-fuzz.
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122. Copyright (C) 2011 by Krzysztof Kowalik <chris@nu7hat.ch>
Package fragbag provides interfaces for using fragment libraries along with several implementations of fragment libraries. This package makes it possible for clients to define their own fragment libraries while reusing all of the infrastructure which operates on fragment libraries. The central type of this package is the Library interface, along with its child interfaces: SequenceLibrary, StructureLibrary and WeightedLibrary. The Library interface states that all libraries have names, some collection of fragments of uniform size, possibly a sub library and a uniquely identifying tag. The tag is used to recapitulate the type of the fragment library (from the Openers map) when reading them from disk. Libraries may also wrap other libraries to provide additional functionality. For example, the WeightedLibrary interface describes any fragment library that can weight the raw frequency of a fragment against a query. But this functionality can be added to existing libraries by wrapping them with additional information. (For example, see the implementation of the WeightedTfIdf library.) A central design decision of this package is that all fragment libraries are immutable. Once they are created, they cannot be changed. Therefore, all actions defined by the Library interfaces never mutate an existing library.
Package goenvconfig provides immutability for configuration automatically loaded from environment variables.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.
Package numeric contains structs and interfaces that represent numeric types. It creates wrappers around numeric types, giving them a common interface that can be used to handle numbers (see Numeric interface) and a type that provides user-friendly interaction (see Number type). This package is not intended to replace the builtin types (int, float64, ...), but rather to make number manipulation easier in cases where it's necessary to support a wide range of approximated numbers without the performance penalty of always using an arbitrary precision type (big.Int and big.Rat). It's important to note that since one of the Numeric types is Float, calculations that require exact numbers or decimal precision should not use this package. All types in this package are immutable. The default implementations of the Numeric interface (see Float and BigFloat) are aliases to the builtin types (float64 and big.Rat) and, therefore, one may obtain a Numeric value by simply casting to the Numeric type: However, Numeric types are merely wrappers around their builtin counterparts and don't provide support for automatic conversion between Numeric types, e.g., when a Float value reaches infinity and needs to be converted to a BigFloat. In order to get automatic promotion from a smaller type (e.g. Float) to a larger type (e.g. BigFloat), the Number type should be used. A value of Number type can be created through the NewNumber() and NewNumberSafe() methods. Both methods accept an arbitrary type (interface{}), and attempt to convert it to a Number value. If such a conversion does not exist, NewNumberSafe() will return an error and NewNumber() will panic.
This package is the root package of the govmomi library. The library is structured as follows: The minimal usable functionality is available through the vim25 package. It contains subpackages that contain generated types, managed objects, and all available methods. The vim25 package is entirely independent of the other packages in the govmomi tree -- it has no dependencies on its peers. The vim25 package itself contains a client structure that is passed around throughout the entire library. It abstracts a session and its immutable state. See the vim25 package for more information. The session package contains an abstraction for the session manager that allows a user to login and logout. It also provides access to the current session (i.e. to determine if the user is in fact logged in) The object package contains wrappers for a selection of managed objects. The constructors of these objects all take a *vim25.Client, which they pass along to derived objects, if applicable. The govc package contains the govc CLI. The code in this tree is not intended to be used as a library. Any functionality that govc contains that _could_ be used as a library function but isn't, _should_ live in a root level package. Other packages, such as "event", "guest", or "license", provide wrappers for the respective subsystems. They are typically not needed in normal workflows so are kept outside the object package.