Add tracking of function parameters (#2552)

For parameters (and in the future, arguments too; generally comma-separated lists) track two node blocks:

1. param_ir: The complete IR.
2. param_refs: Nodes within the IR that are the "root" parameter.

param_refs should allow quick counting of the # of parameters, and more efficient comparison of call args with function parameters. param_ir should be necessary to generate the actual signature.

In order to construct this, this refactors the node_block_stack into its own class, which is reused in params_stack. These carry references to the underlying SmallVector for lazy modification in order to avoid a dependency cycle with SemanticsIR (also see notes on empty node blocks below).

When finalized, the block pair is pushed onto finished_params_stack. That's because node_stack only has space for one thing, and this is two things -- so I'm essentially choosing a trade-off of adding another stack in order to avoid consuming more space in the expectation that most parse nodes have 0 or 1 things to return, and 2 will be very rare.

As factored, this currently consolidates most empty node blocks into a single canonical empty node block. This is because I think empty blocks, i.e. `()`, will be very common. In order to achieve this, SemanticsNodeBlockStack does lazy creation.

An alternative approach would have been to use 1 node block per parameter. We decided against this in order to reduce the number of vectors being created.

toolchain/semantics/semantics_node_block_stack.h

@@ -0,0 +1,65 @@
+// Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+// Exceptions. See /LICENSE for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+#ifndef CARBON_TOOLCHAIN_SEMANTICS_SEMANTICS_NODE_BLOCK_STACK_H_
+#define CARBON_TOOLCHAIN_SEMANTICS_SEMANTICS_NODE_BLOCK_STACK_H_
+
+#include <type_traits>
+
+#include "common/check.h"
+#include "llvm/ADT/SmallVector.h"
+#include "toolchain/semantics/semantics_node.h"
+
+namespace Carbon {
+
+// Wraps the stack of node blocks for SemanticsParseTreeHandler.
+//
+// All pushes and pops will be vlogged.
+class SemanticsNodeBlockStack {
+ public:
+  explicit SemanticsNodeBlockStack(
+      llvm::SmallVector<llvm::SmallVector<SemanticsNodeId>>& node_blocks,
+      llvm::raw_ostream* vlog_stream)
+      : node_blocks_(&node_blocks), vlog_stream_(vlog_stream) {}
+
+  ~SemanticsNodeBlockStack() { CARBON_CHECK(stack_.empty()) << stack_.size(); }
+
+  // Pushes a new node block. It will be invalid unless PeekForAdd is called in
+  // order to support lazy allocation.
+  auto Push() -> void;
+
+  // Pushes a new node block.
+  // TODO: Try to remove this in favor of the lazy alloc in Push.
+  auto PushWithUnconditionalAlloc() -> SemanticsNodeBlockId;
+
+  // Peeks at the top node block. This does not trigger lazy allocation, so the
+  // returned node block may be invalid.
+  auto Peek() -> SemanticsNodeBlockId { return stack_.back(); }
+
+  // Returns the top node block, allocating one if it's still invalid.
+  auto PeekForAdd() -> SemanticsNodeBlockId;
+
+  // Pops the top node block. This will always return a valid node block;
+  // SemanticsNodeBlockId::Empty is returned if one wasn't allocated.
+  auto Pop() -> SemanticsNodeBlockId;
+
+  // Prints the stack for a stack dump.
+  auto PrintForStackDump(llvm::raw_ostream& output) const -> void;
+
+ private:
+  // The underlying node block storage on SemanticsIR. Always non-null.
+  llvm::SmallVector<llvm::SmallVector<SemanticsNodeId>>* const node_blocks_;
+
+  // Whether to print verbose output.
+  llvm::raw_ostream* vlog_stream_;
+
+  // The actual stack.
+  // PushEntry and PopEntry control modification in order to centralize
+  // vlogging.
+  llvm::SmallVector<SemanticsNodeBlockId> stack_;
+};
+
+}  // namespace Carbon
+
+#endif  // CARBON_TOOLCHAIN_SEMANTICS_SEMANTICS_NODE_BLOCK_STACK_H_