Breaking changes in coming v3.0

[lni]

The coming new release will have the version number bumped to v3.0. It is a major release with the following breaking changes -

• NewNodeHost now returns error when it fails to create a new NodeHost instance.

Your existing code is probably doing this -

nh := dragonboat.NewNodeHost(nhc)

Please update it to

nh, err := dragonboat.NewNodeHost(nhc)
if err != nil {
  panic(err) // or other err handling you want
}

• In v3.0, the Update method in IStateMachine will be updated to return a Result instance and an error, it contains both an uint64 integer value and a byte slice. This is based on user request to support CompareAndSwap style operation.

Existing user applications can be easily updated to use the new API. For existing Update() method:

return v

should be changed to:

return statemachine.Result{Value: v}, nil 

• in v3.0, the Lookup method's signature will be changed to be Lookup(interface{}) (interface{}, error)

you can also choose to implement the optional NALookup([]byte) ([]byte, error) method to retain the old interface and behaviour.

• in v3.0, the GetHash method will be changed to return (uint64, error), it also becomes an optional method, you no longer have to implement it.

• In v3.0, the SaveSnapshot no longer require the number of written bytes to be returned. This is based on observation that multiple users got confused by the existing API.

Existing user applications can be easily updated to use the new API. For existing SaveSnapshot() method:

return numOfWrittenBytes, nil

should be changed to

return nil

Note that the v2.x release will continue to be supported for fixing critical bugs. Users are free to choose whether to the use v2.x which is more stable or v3.0 for more advanced features.

• Drummer has been moved into the internal package. The MasterClient interface has been replaced by a GetNodeHostInfo() API.

• The C++ binding will be removed from the dragonboat repo. It might be moved to a separate repo in the future if someone can offer to maintain it.

[zhengxiaochuan-3]

what about #34 #35 in v3.0 ?

[lni]

@zhengxiaochuan-3

they are not breaking changes, just some new features.

both have been implemented & extensively tested. will make them publicly available as a feature branch later this week. Looking forward to have your feedbacks. :)

[riaan53]

Thank you! Been trying to figure out a way to add subscribers or notifiers and the new update signature sounds like it should work perfectly for that. Looking forward to the new release and thank you for the awesome work.

[lni]

@zhengxiaochuan-3 @riaan53

all breaking changes mentioned above have been implemented in the beta v3.0 release, https://github.com/lni/dragonboat/tree/beta-release-3.0

please feel free to raise issues if you see anything broken or strange. thanks!

[riaan53]

Awesome thank you! The disk based state machine looks fantastic and fits my usecase better than pure in mem. Any reason for the fork of gorocksdb or can I just use the original?

[lni]

Hi @riaan53

The patched version of gorocksdb included in dragonboat has some extensions, e.g. the OKey() and OValue() methods of the Iterator type. Most of them were added to avoid extra allocations. I didn't try to upstream my changes as the original interface seem to be complete and it is mostly a one-to-one mapping of the RocksDB's interface, introducing such extra methods for minor performance gain might not be the general goal of the gorocksdb project.

Another change I made to the included gorocksdb package in v3.0 beta is to allow users to use the original gorocksdb in their own dragonboat based applications. All exported names have been renamed from gorocksdb_* to dragonboat_*.

Below is a link to the on disk state machine example, as you can see, it includes a copy of the original gorocksdb (with *_test.go removed). When you run this example, there are actually two versions of gorocksdb running in the same process.

https://github.com/lni/dragonboat-example/tree/on-disk-state-machine/ondisk