Skip to content

Commit

Permalink
Corrected texts
Browse files Browse the repository at this point in the history
  • Loading branch information
criadoperez authored and rvagg committed Sep 21, 2023
1 parent 05e58cc commit 993665b
Show file tree
Hide file tree
Showing 7 changed files with 10 additions and 10 deletions.
6 changes: 3 additions & 3 deletions HACKME_builderBehaviors.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ high level rules of builders and assemblers
- The purpose of this is to prevent accidental mutation after any validations have been performed during the "finish" processing.

- Many methods must be called in the right order, and the user must not hold onto references after calling "finish" methods on them.
- The reason this is important is to enable assembler systems to agressively reuse memory, thus increasing performance.
- The reason this is important is to enable assembler systems to aggressively reuse memory, thus increasing performance.
- Thus, if you hold onto NodeAssembler reference after being finished with it... you can't assume it'll explicitly error if you call further methods on it, because it might now be operating again... _on a different target_.
- In recursive structures, calling AssembleKey or AssembleValue might return pointer-identical assemblers (per warning in previous bullet), but the memory their assembly is targetted to should always advance -- it should never target already-assembled memory.
- In recursive structures, calling AssembleKey or AssembleValue might return pointer-identical assemblers (per warning in previous bullet), but the memory their assembly is targeted to should always advance -- it should never target already-assembled memory.
- (If you're thinking "the Rust memory model would be able to greatly enhance safety here!"... yes. Yes it would.)
- When misuses of order are detected, these may cause panics (rather than error returns) (not all methods that can be so misused have error returns).

Expand Down Expand Up @@ -53,7 +53,7 @@ but the caller tries to continue anyway.
- is typically implemented by nil'ing the wip node they point to.
- this means you get nil pointer dereference panics when attempting to use an assembler after it's finished... which is not the greatest error message.
- but it does save us a lot of check code for a situation that the user certainly shouldn't get into in the first place.
- (worth review: can we add that check code without extra runtime cost? possibly, because the compiler might then skip its own implicit check branches. might still increase SLOC noticably in codegen output, though.)
- (worth review: can we add that check code without extra runtime cost? possibly, because the compiler might then skip its own implicit check branches. might still increase SLOC noticeably in codegen output, though.)
- worth noting there's a limit to how good this can be anyway: it's "best effort" error reporting: see the remarks on reuse of assembler memory in "overall rules" above.
- it's systemically critical to not yield an assembler _ever again in the future_ that refers to some memory already considered finished.
- even though we no longer return intermediate nodes, there's still many ways this could produce problems. For example, complicating (if not outright breaking) COW sharing of segments of data.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ Projects wishing to migrate can do so smoothly and at their leisure.

We now consider many of the earlier golang IPLD libraries to be defacto deprecated,
and you should expect new features *here*, rather than in those libraries.
(Those libraries still won't be going away anytime soon, but we really don't recomend new construction on them.)
(Those libraries still won't be going away anytime soon, but we really don't recommend new construction on them.)

### migrating

Expand Down
4 changes: 2 additions & 2 deletions multicodec/defaultRegistry.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ func LookupEncoder(indicator uint64) (codec.Encoder, error) {
// its contents are not particularly stable.
// In particular, it is not recommended to make any behaviors of your program conditional
// based on information returned by this function -- if your program needs conditional
// behavior based on registred codecs, you may want to consider taking more explicit control
// behavior based on registered codecs, you may want to consider taking more explicit control
// and using your own non-default registry.
func ListEncoders() []uint64 {
return DefaultRegistry.ListEncoders()
Expand Down Expand Up @@ -110,7 +110,7 @@ func LookupDecoder(indicator uint64) (codec.Decoder, error) {
// its contents are not particularly stable.
// In particular, it is not recommended to make any behaviors of your program conditional
// based on information returned by this function -- if your program needs conditional
// behavior based on registred codecs, you may want to consider taking more explicit control
// behavior based on registered codecs, you may want to consider taking more explicit control
// and using your own non-default registry.
func ListDecoders() []uint64 {
return DefaultRegistry.ListDecoders()
Expand Down
2 changes: 1 addition & 1 deletion storage/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ type StreamingReadableStorage interface {
// The PutStream function returns three parameters: an io.Writer (as you'd expect), another function, and an error.
// The function returned is called a "WriteCommitter".
// The final error value is as usual: it will contain an error value if the write could not be begun.
// ("WriteCommitter" will be refered to as such throughout the docs, but we don't give it a named type --
// ("WriteCommitter" will be referred to as such throughout the docs, but we don't give it a named type --
// unfortunately, this is important, because we don't want to force implementers of storage systems to import this package just for a type name.)
//
// The WriteCommitter function should be called when you're done writing,
Expand Down
2 changes: 1 addition & 1 deletion storage/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@
// This is intentional, and was done very carefully.
// If implementing a storage system, you should find it possible to do so *without* importing this package.
// Because only standard library types are present in the interface contracts,
// it's possible to implement types that align with the interfaces without refering to them.
// it's possible to implement types that align with the interfaces without referring to them.
//
// Note that where keys are discussed in this package, they use the golang string type --
// however, they may be binary. (The golang string type allows arbitrary bytes in general,
Expand Down
2 changes: 1 addition & 1 deletion storage/tests/benchmarks.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ func BenchPut(b *testing.B, store storage.WritableStorage, gen Gen, scale int) {
// in practice, starting and stopping this frequently causes:
// - alloc count to be reported *correctly* (which is nice)
// - but reported ns/op to become erratic, and inflated (not at all nice)
// - and actuall wall-clock run time to increase drastically (~22x!) (not deadly, but certainly unpleasant)
// - and actual wall-clock run time to increase drastically (~22x!) (not deadly, but certainly unpleasant)
// It may be best to write a synthetic dummy benchmark to see how much the gen function costs, and subtract that from the other results.
//b.StopTimer()
key, content := gen()
Expand Down
2 changes: 1 addition & 1 deletion traversal/patch/patch.ipldsch
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Op represents the kind of operation to perfrom
# Op represents the kind of operation to perform
# The current set is based on the JSON Patch specification
# We may end up adding more operations in the future
type Op enum {
Expand Down

0 comments on commit 993665b

Please sign in to comment.