text: // Copyright 2014 The Crashpad Authors. All rights reserved.
  //
  // 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
  //
  //     http://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.
  
  #ifndef CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_
  #define CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_
  
  #include <mach/mach.h>
  
  namespace crashpad {
  
  //! \brief `MACH_PORT_NULL` with the correct type for a Mach port,
  //!     `mach_port_t`.
  //!
  //! For situations where implicit conversions between signed and unsigned types
  //! are not performed, use kMachPortNull instead of an explicit `implicit_cast`
  //! of `MACH_PORT_NULL` to `mach_port_t`. This is useful for logging and testing
  //! assertions.
  const mach_port_t kMachPortNull = MACH_PORT_NULL;
  
  //! \brief `MACH_EXCEPTION_CODES` with the correct type for a Mach exception
  //!     behavior, `exception_behavior_t`.
  //!
  //! Signedness problems can occur when ORing `MACH_EXCEPTION_CODES` as a signed
  //! integer, because a signed integer overflow results. This constant can be
  //! used instead of `MACH_EXCEPTION_CODES` in such cases.
  const exception_behavior_t kMachExceptionCodes = MACH_EXCEPTION_CODES;
  
  // Because exception_mask_t is an int and has one bit for each defined
  // exception_type_t, it’s reasonable to assume that there cannot be any
  // officially-defined exception_type_t values higher than 31.
  // kMachExceptionSimulated uses a value well outside this range because it does
  // not require a corresponding mask value. Simulated exceptions are delivered to
  // the exception handler registered for EXC_CRASH exceptions using
  // EXC_MASK_CRASH.
  
  //! \brief An exception type to use for simulated exceptions.
  const exception_type_t kMachExceptionSimulated = 'CPsx';
  
  //! \brief A const version of `thread_state_t`.
  //!
  //! This is useful as the \a old_state parameter to exception handler functions.
  //! Normally, these parameters are of type `thread_state_t`, but this allows
  //! modification of the state, which is conceptually `const`.
  using ConstThreadState = const natural_t*;
  
  //! \brief Like `mach_thread_self()`, but without the obligation to release the
  //!     send right.
  //!
  //! `mach_thread_self()` returns a send right to the current thread port,
  //! incrementing its reference count. This burdens the caller with maintaining
  //! this send right, and calling `mach_port_deallocate()` when it is no longer
  //! needed. This is burdensome, and is at odds with the normal operation of
  //! `mach_task_self()`, which does not increment the task port’s reference count
  //! whose result must not be deallocated.
  //!
  //! Callers can use this function in preference to `mach_thread_self()`. This
  //! function returns an extant reference to the current thread’s port without
  //! incrementing its reference count.
  //!
  //! \return The value of `mach_thread_self()` without incrementing its reference
  //!     count. The returned port must not be deallocated by
  //!     `mach_port_deallocate()`. The returned value is valid as long as the
  //!     thread continues to exist as a `pthread_t`.
  thread_t MachThreadSelf();
  
  //! \brief Creates a new Mach port in the current task.
  //!
  //! This function wraps the `mach_port_allocate()` providing a simpler
  //! interface.
  //!
  //! \param[in] right The type of right to create.
  //!
  //! \return The new Mach port. On failure, `MACH_PORT_NULL` with a message
  //!     logged.
  mach_port_t NewMachPort(mach_port_right_t right);
  
  //! \brief The value for `EXC_MASK_ALL` appropriate for the operating system at
  //!     run time.
  //!
  //! The SDK’s definition of `EXC_MASK_ALL` has changed over time, with later
  //! versions containing more bits set than earlier versions. However, older
  //! kernels will reject exception masks that contain bits set that they don’t
  //! recognize. Calling this function will return a value for `EXC_MASK_ALL`
  //! appropriate for the system at run time.
  //!
  //! \note `EXC_MASK_ALL` does not include the value of `EXC_MASK_CRASH`.
  //!     Consumers that want `EXC_MASK_ALL` along with `EXC_MASK_CRASH` must use
  //!     ExcMaskAll() | `EXC_MASK_CRASH` explicitly.
  exception_mask_t ExcMaskAll();
  
  }  // namespace crashpad
  
  #endif  // CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_
  