225 lines
10 KiB
C++
225 lines
10 KiB
C++
// Copyright 2023 The Abseil Authors.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// https://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// File: nullability.h
|
|
// -----------------------------------------------------------------------------
|
|
//
|
|
// This header file defines a set of "templated annotations" for designating the
|
|
// expected nullability of pointers. These annotations allow you to designate
|
|
// pointers in one of three classification states:
|
|
//
|
|
// * "Non-null" (for pointers annotated `Nonnull<T>`), indicating that it is
|
|
// invalid for the given pointer to ever be null.
|
|
// * "Nullable" (for pointers annotated `Nullable<T>`), indicating that it is
|
|
// valid for the given pointer to be null.
|
|
// * "Unknown" (for pointers annotated `NullabilityUnknown<T>`), indicating
|
|
// that the given pointer has not been yet classified as either nullable or
|
|
// non-null. This is the default state of unannotated pointers.
|
|
//
|
|
// NOTE: unannotated pointers implicitly bear the annotation
|
|
// `NullabilityUnknown<T>`; you should rarely, if ever, see this annotation used
|
|
// in the codebase explicitly.
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// Nullability and Contracts
|
|
// -----------------------------------------------------------------------------
|
|
//
|
|
// These nullability annotations allow you to more clearly specify contracts on
|
|
// software components by narrowing the *preconditions*, *postconditions*, and
|
|
// *invariants* of pointer state(s) in any given interface. It then depends on
|
|
// context who is responsible for fulfilling the annotation's requirements.
|
|
//
|
|
// For example, a function may receive a pointer argument. Designating that
|
|
// pointer argument as "non-null" tightens the precondition of the contract of
|
|
// that function. It is then the responsibility of anyone calling such a
|
|
// function to ensure that the passed pointer is not null.
|
|
//
|
|
// Similarly, a function may have a pointer as a return value. Designating that
|
|
// return value as "non-null" tightens the postcondition of the contract of that
|
|
// function. In this case, however, it is the responsibility of the function
|
|
// itself to ensure that the returned pointer is not null.
|
|
//
|
|
// Clearly defining these contracts allows providers (and consumers) of such
|
|
// pointers to have more confidence in their null state. If a function declares
|
|
// a return value as "non-null", for example, the caller should not need to
|
|
// check whether the returned value is `nullptr`; it can simply assume the
|
|
// pointer is valid.
|
|
//
|
|
// Of course most interfaces already have expectations on the nullability state
|
|
// of pointers, and these expectations are, in effect, a contract; often,
|
|
// however, those contracts are either poorly or partially specified, assumed,
|
|
// or misunderstood. These nullability annotations are designed to allow you to
|
|
// formalize those contracts within the codebase.
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// Using Nullability Annotations
|
|
// -----------------------------------------------------------------------------
|
|
//
|
|
// It is important to note that these annotations are not distinct strong
|
|
// *types*. They are alias templates defined to be equal to the underlying
|
|
// pointer type. A pointer annotated `Nonnull<T*>`, for example, is simply a
|
|
// pointer of type `T*`. Each annotation acts as a form of documentation about
|
|
// the contract for the given pointer. Each annotation requires providers or
|
|
// consumers of these pointers across API boundaries to take appropriate steps
|
|
// when setting or using these pointers:
|
|
//
|
|
// * "Non-null" pointers should never be null. It is the responsibility of the
|
|
// provider of this pointer to ensure that the pointer may never be set to
|
|
// null. Consumers of such pointers can treat such pointers as non-null.
|
|
// * "Nullable" pointers may or may not be null. Consumers of such pointers
|
|
// should precede any usage of that pointer (e.g. a dereference operation)
|
|
// with a a `nullptr` check.
|
|
// * "Unknown" pointers may be either "non-null" or "nullable" but have not been
|
|
// definitively determined to be in either classification state. Providers of
|
|
// such pointers across API boundaries should determine -- over time -- to
|
|
// annotate the pointer in either of the above two states. Consumers of such
|
|
// pointers across an API boundary should continue to treat such pointers as
|
|
// they currently do.
|
|
//
|
|
// Example:
|
|
//
|
|
// // PaySalary() requires the passed pointer to an `Employee` to be non-null.
|
|
// void PaySalary(absl::Nonnull<Employee *> e) {
|
|
// pay(e->salary); // OK to dereference
|
|
// }
|
|
//
|
|
// // CompleteTransaction() guarantees the returned pointer to an `Account` to
|
|
// // be non-null.
|
|
// absl::Nonnull<Account *> balance CompleteTransaction(double fee) {
|
|
// ...
|
|
// }
|
|
//
|
|
// // Note that specifying a nullability annotation does not prevent someone
|
|
// // from violating the contract:
|
|
//
|
|
// Nullable<Employee *> find(Map& employees, std::string_view name);
|
|
//
|
|
// void g(Map& employees) {
|
|
// Employee *e = find(employees, "Pat");
|
|
// // `e` can now be null.
|
|
// PaySalary(e); // Violates contract, but compiles!
|
|
// }
|
|
//
|
|
// Nullability annotations, in other words, are useful for defining and
|
|
// narrowing contracts; *enforcement* of those contracts depends on use and any
|
|
// additional (static or dynamic analysis) tooling.
|
|
//
|
|
// NOTE: The "unknown" annotation state indicates that a pointer's contract has
|
|
// not yet been positively identified. The unknown state therefore acts as a
|
|
// form of documentation of your technical debt, and a codebase that adopts
|
|
// nullability annotations should aspire to annotate every pointer as either
|
|
// "non-null" or "nullable".
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// Applicability of Nullability Annotations
|
|
// -----------------------------------------------------------------------------
|
|
//
|
|
// By default, nullability annotations are applicable to raw and smart
|
|
// pointers. User-defined types can indicate compatibility with nullability
|
|
// annotations by providing an `absl_nullability_compatible` nested type. The
|
|
// actual definition of this inner type is not relevant as it is used merely as
|
|
// a marker. It is common to use a using declaration of
|
|
// `absl_nullability_compatible` set to void.
|
|
//
|
|
// // Example:
|
|
// struct MyPtr {
|
|
// using absl_nullability_compatible = void;
|
|
// ...
|
|
// };
|
|
//
|
|
// DISCLAIMER:
|
|
// ===========================================================================
|
|
// These nullability annotations are primarily a human readable signal about the
|
|
// intended contract of the pointer. They are not *types* and do not currently
|
|
// provide any correctness guarantees. For example, a pointer annotated as
|
|
// `Nonnull<T*>` is *not guaranteed* to be non-null, and the compiler won't
|
|
// alert or prevent assignment of a `Nullable<T*>` to a `Nonnull<T*>`.
|
|
// ===========================================================================
|
|
#ifndef ABSL_BASE_NULLABILITY_H_
|
|
#define ABSL_BASE_NULLABILITY_H_
|
|
|
|
#include "absl/base/internal/nullability_impl.h"
|
|
|
|
namespace absl {
|
|
|
|
// absl::Nonnull
|
|
//
|
|
// The indicated pointer is never null. It is the responsibility of the provider
|
|
// of this pointer across an API boundary to ensure that the pointer is never be
|
|
// set to null. Consumers of this pointer across an API boundary may safely
|
|
// dereference the pointer.
|
|
//
|
|
// Example:
|
|
//
|
|
// // `employee` is designated as not null.
|
|
// void PaySalary(absl::Nonnull<Employee *> employee) {
|
|
// pay(*employee); // OK to dereference
|
|
// }
|
|
template <typename T>
|
|
using Nonnull = nullability_internal::NonnullImpl<T>;
|
|
|
|
// absl::Nullable
|
|
//
|
|
// The indicated pointer may, by design, be either null or non-null. Consumers
|
|
// of this pointer across an API boundary should perform a `nullptr` check
|
|
// before performing any operation using the pointer.
|
|
//
|
|
// Example:
|
|
//
|
|
// // `employee` may be null.
|
|
// void PaySalary(absl::Nullable<Employee *> employee) {
|
|
// if (employee != nullptr) {
|
|
// Pay(*employee); // OK to dereference
|
|
// }
|
|
// }
|
|
template <typename T>
|
|
using Nullable = nullability_internal::NullableImpl<T>;
|
|
|
|
// absl::NullabilityUnknown (default)
|
|
//
|
|
// The indicated pointer has not yet been determined to be definitively
|
|
// "non-null" or "nullable." Providers of such pointers across API boundaries
|
|
// should, over time, annotate such pointers as either "non-null" or "nullable."
|
|
// Consumers of these pointers across an API boundary should treat such pointers
|
|
// with the same caution they treat currently unannotated pointers. Most
|
|
// existing code will have "unknown" pointers, which should eventually be
|
|
// migrated into one of the above two nullability states: `Nonnull<T>` or
|
|
// `Nullable<T>`.
|
|
//
|
|
// NOTE: Because this annotation is the global default state, pointers without
|
|
// any annotation are assumed to have "unknown" semantics. This assumption is
|
|
// designed to minimize churn and reduce clutter within the codebase.
|
|
//
|
|
// Example:
|
|
//
|
|
// // `employee`s nullability state is unknown.
|
|
// void PaySalary(absl::NullabilityUnknown<Employee *> employee) {
|
|
// Pay(*employee); // Potentially dangerous. API provider should investigate.
|
|
// }
|
|
//
|
|
// Note that a pointer without an annotation, by default, is assumed to have the
|
|
// annotation `NullabilityUnknown`.
|
|
//
|
|
// // `employee`s nullability state is unknown.
|
|
// void PaySalary(Employee* employee) {
|
|
// Pay(*employee); // Potentially dangerous. API provider should investigate.
|
|
// }
|
|
template <typename T>
|
|
using NullabilityUnknown = nullability_internal::NullabilityUnknownImpl<T>;
|
|
|
|
} // namespace absl
|
|
|
|
#endif // ABSL_BASE_NULLABILITY_H_
|