Merge pull request #8133 from obsidiansystems/improve-internal-api-docs

Extend internal API docs, part 2
This commit is contained in:
John Ericson 2023-04-01 12:42:03 -04:00 committed by GitHub
commit ea1cbc3df5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
145 changed files with 803 additions and 359 deletions

View file

@ -1,10 +1,20 @@
#pragma once
///@file
#include "installable-value.hh" #include "installable-value.hh"
#include "command.hh" #include "command.hh"
namespace nix { namespace nix {
/**
* An InstallableCommand where the single positional argument must be an
* InstallableValue in particular.
*/
struct InstallableValueCommand : InstallableCommand struct InstallableValueCommand : InstallableCommand
{ {
/**
* Entry point to this command
*/
virtual void run(ref<Store> store, ref<InstallableValue> installable) = 0; virtual void run(ref<Store> store, ref<InstallableValue> installable) = 0;
void run(ref<Store> store, ref<Installable> installable) override; void run(ref<Store> store, ref<Installable> installable) override;

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "installable-value.hh" #include "installable-value.hh"
#include "args.hh" #include "args.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "args.hh" #include "args.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,3 +1,6 @@
#pragma once
///@file
#include "globals.hh" #include "globals.hh"
#include "installable-value.hh" #include "installable-value.hh"
#include "outputs-spec.hh" #include "outputs-spec.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "installables.hh" #include "installables.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "installable-value.hh" #include "installable-value.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "installables.hh" #include "installables.hh"
#include "flake/flake.hh" #include "flake/flake.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"
#include "path.hh" #include "path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <functional> #include <functional>
#include <map> #include <map>

View file

@ -1,3 +1,6 @@
#pragma once
///@file
#include "types.hh" #include "types.hh"
namespace nix { namespace nix {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "nixexpr.hh" #include "nixexpr.hh"
#include "symbol-table.hh" #include "symbol-table.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "sync.hh" #include "sync.hh"
#include "hash.hh" #include "hash.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "attr-set.hh" #include "attr-set.hh"
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "flakeref.hh" #include "flakeref.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "hash.hh" #include "hash.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "flakeref.hh" #include "flakeref.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"
#include "path.hh" #include "path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <map> #include <map>
#include <vector> #include <vector>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <list> #include <list>
#include <map> #include <map>

View file

@ -1,3 +1,6 @@
#pragma once
///@file
#include <gtest/gtest.h> #include <gtest/gtest.h>
#include <gmock/gmock.h> #include <gmock/gmock.h>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <rapidcheck/gen/Arbitrary.h> #include <rapidcheck/gen/Arbitrary.h>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "nixexpr.hh" #include "nixexpr.hh"
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "nixexpr.hh" #include "nixexpr.hh"
#include "eval.hh" #include "eval.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <cassert> #include <cassert>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"
#include "comparator.hh" #include "comparator.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "fetchers.hh" #include "fetchers.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "config.hh" #include "config.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "hash.hh" #include "hash.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "fetchers.hh" #include "fetchers.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "args.hh" #include "args.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "logging.hh" #include "logging.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"
#include "args.hh" #include "args.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "crypto.hh" #include "crypto.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "realisation.hh" #include "realisation.hh"
#include "derived-path.hh" #include "derived-path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "parsed-derivations.hh" #include "parsed-derivations.hh"
#include "lock.hh" #include "lock.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"
#include "goal.hh" #include "goal.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "logging.hh" #include "logging.hh"
#include "serialise.hh" #include "serialise.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "derivation-goal.hh" #include "derivation-goal.hh"
#include "local-store.hh" #include "local-store.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <string> #include <string>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "lock.hh" #include "lock.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "lock.hh" #include "lock.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "derivations.hh" #include "derivations.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "derivations.hh" #include "derivations.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <variant> #include <variant>
#include "hash.hh" #include "hash.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "serialise.hh" #include "serialise.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "path.hh" #include "path.hh"
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"
#include "path.hh" #include "path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "hash.hh" #include "hash.hh"
@ -87,39 +88,56 @@ struct FileTransfer
{ {
virtual ~FileTransfer() { } virtual ~FileTransfer() { }
/* Enqueue a data transfer request, returning a future to the result of /**
the download. The future may throw a FileTransferError * Enqueue a data transfer request, returning a future to the result of
exception. */ * the download. The future may throw a FileTransferError
* exception.
*/
virtual void enqueueFileTransfer(const FileTransferRequest & request, virtual void enqueueFileTransfer(const FileTransferRequest & request,
Callback<FileTransferResult> callback) = 0; Callback<FileTransferResult> callback) = 0;
std::future<FileTransferResult> enqueueFileTransfer(const FileTransferRequest & request); std::future<FileTransferResult> enqueueFileTransfer(const FileTransferRequest & request);
/* Synchronously download a file. */ /**
* Synchronously download a file.
*/
FileTransferResult download(const FileTransferRequest & request); FileTransferResult download(const FileTransferRequest & request);
/* Synchronously upload a file. */ /**
* Synchronously upload a file.
*/
FileTransferResult upload(const FileTransferRequest & request); FileTransferResult upload(const FileTransferRequest & request);
/* Download a file, writing its data to a sink. The sink will be /**
invoked on the thread of the caller. */ * Download a file, writing its data to a sink. The sink will be
* invoked on the thread of the caller.
*/
void download(FileTransferRequest && request, Sink & sink); void download(FileTransferRequest && request, Sink & sink);
enum Error { NotFound, Forbidden, Misc, Transient, Interrupted }; enum Error { NotFound, Forbidden, Misc, Transient, Interrupted };
}; };
/* Return a shared FileTransfer object. Using this object is preferred /**
because it enables connection reuse and HTTP/2 multiplexing. */ * @return a shared FileTransfer object.
*
* Using this object is preferred because it enables connection reuse
* and HTTP/2 multiplexing.
*/
ref<FileTransfer> getFileTransfer(); ref<FileTransfer> getFileTransfer();
/* Return a new FileTransfer object. */ /**
* @return a new FileTransfer object
*
* Prefer getFileTransfer() to this; see its docs for why.
*/
ref<FileTransfer> makeFileTransfer(); ref<FileTransfer> makeFileTransfer();
class FileTransferError : public Error class FileTransferError : public Error
{ {
public: public:
FileTransfer::Error error; FileTransfer::Error error;
std::optional<std::string> response; // intentionally optional /// intentionally optional
std::optional<std::string> response;
template<typename... Args> template<typename... Args>
FileTransferError(FileTransfer::Error error, std::optional<std::string> response, const Args & ... args); FileTransferError(FileTransfer::Error error, std::optional<std::string> response, const Args & ... args);

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "config.hh" #include "config.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"
#include "gc-store.hh" #include "gc-store.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "sqlite.hh" #include "sqlite.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <memory> #include <memory>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <functional> #include <functional>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "ref.hh" #include "ref.hh"
#include "nar-info.hh" #include "nar-info.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "hash.hh" #include "hash.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <cassert> #include <cassert>
#include <optional> #include <optional>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "derivations.hh" #include "derivations.hh"
#include "store-api.hh" #include "store-api.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "crypto.hh" #include "crypto.hh"
#include "path.hh" #include "path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
namespace nix { namespace nix {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "path.hh" #include "path.hh"
#include "derived-path.hh" #include "derived-path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <string_view> #include <string_view>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "types.hh" #include "types.hh"
#include "pathlocks.hh" #include "pathlocks.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <variant> #include <variant>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "hash.hh" #include "hash.hh"
#include "path.hh" #include "path.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "fs-accessor.hh" #include "fs-accessor.hh"
#include "ref.hh" #include "ref.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <limits> #include <limits>
#include <string> #include <string>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
namespace nix { namespace nix {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "binary-cache-store.hh" #include "binary-cache-store.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#if ENABLE_S3 #if ENABLE_S3

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
namespace nix { namespace nix {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <functional> #include <functional>
#include <string> #include <string>

View file

@ -1,3 +1,6 @@
#pragma once
///@file
#include "store-api.hh" #include "store-api.hh"
namespace nix { namespace nix {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "util.hh" #include "util.hh"
#include "sync.hh" #include "sync.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "nar-info.hh" #include "nar-info.hh"
#include "realisation.hh" #include "realisation.hh"

View file

@ -1,9 +1,17 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"
namespace nix { namespace nix {
/**
* Helper to try downcasting a Store with a nice method if it fails.
*
* This is basically an alternative to the user-facing part of
* Store::unsupported that allows us to still have a nice message but
* better interface design.
*/
template<typename T> template<typename T>
T & require(Store & store) T & require(Store & store)
{ {

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <rapidcheck/gen/Arbitrary.h> #include <rapidcheck/gen/Arbitrary.h>

View file

@ -1,3 +1,6 @@
#pragma once
///@file
#include <gtest/gtest.h> #include <gtest/gtest.h>
#include <gmock/gmock.h> #include <gmock/gmock.h>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <rapidcheck/gen/Arbitrary.h> #include <rapidcheck/gen/Arbitrary.h>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <rapidcheck/gen/Arbitrary.h> #include <rapidcheck/gen/Arbitrary.h>

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "remote-store.hh" #include "remote-store.hh"
#include "local-fs-store.hh" #include "local-fs-store.hh"

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include "store-api.hh" #include "store-api.hh"
#include "serialise.hh" #include "serialise.hh"
@ -14,6 +15,10 @@ namespace nix {
#define GET_PROTOCOL_MINOR(x) ((x) & 0x00ff) #define GET_PROTOCOL_MINOR(x) ((x) & 0x00ff)
/**
* Enumeration of all the request types for the "worker protocol", used
* by unix:// and ssh-ng:// stores.
*/
typedef enum { typedef enum {
wopIsValidPath = 1, wopIsValidPath = 1,
wopHasSubstitutes = 3, wopHasSubstitutes = 3,
@ -74,7 +79,12 @@ typedef enum {
class Store; class Store;
struct Source; struct Source;
/* To guide overloading */ /**
* Used to guide overloading
*
* See https://en.cppreference.com/w/cpp/language/adl for the broader
* concept of what is going on here.
*/
template<typename T> template<typename T>
struct Phantom {}; struct Phantom {};
@ -103,18 +113,19 @@ MAKE_WORKER_PROTO(X_, Y_);
#undef X_ #undef X_
#undef Y_ #undef Y_
/* These use the empty string for the null case, relying on the fact /**
that the underlying types never serialize to the empty string. * These use the empty string for the null case, relying on the fact
* that the underlying types never serialize to the empty string.
We do this instead of a generic std::optional<T> instance because *
ordinal tags (0 or 1, here) are a bit of a compatability hazard. For * We do this instead of a generic std::optional<T> instance because
the same reason, we don't have a std::variant<T..> instances (ordinal * ordinal tags (0 or 1, here) are a bit of a compatability hazard. For
tags 0...n). * the same reason, we don't have a std::variant<T..> instances (ordinal
* tags 0...n).
We could the generic instances and then these as specializations for *
compatability, but that's proven a bit finnicky, and also makes the * We could the generic instances and then these as specializations for
worker protocol harder to implement in other languages where such * compatability, but that's proven a bit finnicky, and also makes the
specializations may not be allowed. * worker protocol harder to implement in other languages where such
* specializations may not be allowed.
*/ */
MAKE_WORKER_PROTO(, std::optional<StorePath>); MAKE_WORKER_PROTO(, std::optional<StorePath>);
MAKE_WORKER_PROTO(, std::optional<ContentAddress>); MAKE_WORKER_PROTO(, std::optional<ContentAddress>);

View file

@ -1,4 +1,5 @@
#pragma once #pragma once
///@file
#include <nlohmann/json.hpp> #include <nlohmann/json.hpp>
#include "config.hh" #include "config.hh"

Some files were not shown because too many files have changed in this diff Show more