From 48e56e9c53466daa4e221244cbb710c818e0ae8a Mon Sep 17 00:00:00 2001 From: Javi Fontan Date: Sun, 24 Feb 2019 20:45:07 +0100 Subject: [PATCH 1/2] siva: add package documentation Signed-off-by: Javi Fontan --- siva/doc.go | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 siva/doc.go diff --git a/siva/doc.go b/siva/doc.go new file mode 100644 index 0000000..6c4f7e5 --- /dev/null +++ b/siva/doc.go @@ -0,0 +1,75 @@ +/* + +Package siva implements a go-borges library that uses siva files as its +storage backend. + +More information about siva files: https://github.com/src-d/go-siva + +Basics + +In this storage each location contains a single bare git repository that can +contain the objects from several other logical repositories. These logical +repositories are stored as remotes in the configuration file. Its ID is the +remote name but it can also search its URLs. All repositories returned from a +location have the same objects and references. The function AddLocation creates +an empty location that is initialized when using Location.Init. It's +initialization consists of initializing the repository if it's not already +created and adding a remote with its name and URLs to the provided ID. + +For example: + + r1, _ := library.Get("github.com/src-d/go-borges") + println(r1.Name()) # "0168e2c7-eedc-7358-0a09-39ba833bdd54" + r2, _ := library.Get("0168e2c7-eedc-7358-0a09-39ba833bdd54") + println(r1.Name()) # "0168e2c7-eedc-7358-0a09-39ba833bdd54" + + loc, _ := library.AddLocation("test") + r1, _ := loc.Init("repo1") # the first repo initializes the git repository + r1.Commit() + r2, := loc.Init("repos2) # the second just adds a new remote + r2.Commit() + loc.Has("repo1") # true + loc.Has("repo2") # true + +Transactions + +The storage supports transactions and has location lock on transaction when +using the same library. Transactional writes are done directly to the siva file +performing appends and a checkpoint file is created with the size of the file +before starting the transaction. This file is used to recover broken siva files +to the last known good state. Locations can be accessed in read only mode while +the repository is performing a transaction and its content remain stable. + +Committing a transaction finishes the writes to the siva file, closes it and +deletes the checkpoint file. Rollback truncates the siva file to the last good +size and deletes the checkpoint file. + +Only one repository can be opened in read write mode in the same location when +the library is transactional. When a second repository wants to be opened in RW +mode in the same location the library will wait a grace period for the previous +repository to close. By default is 1 minute but it can be configured when +creating the library. + +For example: + + loc, _ := library.Location("foo") + r1, _ := loc.Get("github.com/src-d/go-borges", borges.ReadOnlyMode) + r2, _ := loc.Get("github.com/src-d/go-borges", borges.RWMode) + r2.R().CreateTag("tag", plumbing.ZeroHash, nil) + + r1.R().Tag("tag") # not found + r3, _ := loc.Get("github.com/src-d/go-borges", borges.ReadOnlyMode) + r3.R().Tag("tag") # not found + + # errors after configured timeout as r2 transaction is not completed + r4, _ := loc.Get("github.com/src-d/go-borges", borges.RWMode) + + r2.Commit() + r1.R().Tag("tag") # not found + r5, _ := loc.Get("github.com/src-d/go-borges", borges.ReadOnlyMode) + r5.R().Tag("tag") # found + +Note: When using repositories in non transactional mode you should call Close +after finishing, otherwise the siva file will be corrupted. +*/ +package siva From 49ab543d4930a9c5c6ce5de74d2875cf57ab5d5c Mon Sep 17 00:00:00 2001 From: Javi Fontan Date: Mon, 25 Feb 2019 15:40:59 +0100 Subject: [PATCH 2/2] siva: add information about closing repositories Signed-off-by: Javi Fontan --- siva/doc.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/siva/doc.go b/siva/doc.go index 6c4f7e5..c66ea15 100644 --- a/siva/doc.go +++ b/siva/doc.go @@ -31,6 +31,12 @@ For example: loc.Has("repo1") # true loc.Has("repo2") # true +After use of repositories they should be closed. When the library is +transactional it can be closed with Commit (only for read write mode) or Close +(save changes or rollback). When the library is non transactional it must be +closed with Close. In both cases the repository should not be used again after +closing it. A double Close returns error. + Transactions The storage supports transactions and has location lock on transaction when