-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathIStack.hpp
More file actions
87 lines (78 loc) · 2.58 KB
/
Copy pathIStack.hpp
File metadata and controls
87 lines (78 loc) · 2.58 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
#pragma once
#include <memory>
#include <cstddef>
/**
* @brief Interface for a thread-safe stack.
*
* Provides a minimal and safe API for concurrent stack implementations.
* The design avoids exposing operations that could lead to race conditions
* (e.g., separating `empty()` and `pop()` in an unsafe way).
*/
template <typename T>
class IStack {
public:
virtual ~IStack() = default;
/**
* @brief Pushes a value onto the stack (copy version).
*
* Accepts an lvalue reference to avoid unnecessary temporaries.
*/
virtual void push(const T& value) = 0;
/**
* @brief Pushes a value onto the stack (move version).
*
* Enables efficient insertion of rvalues and move-only types.
*/
virtual void push(T&& value) = 0;
/**
* @brief Removes and returns the top element of the stack.
*
* @return Shared pointer to the removed element.
*
* @throws EmptyStackException if the stack is empty (implementation-defined).
*
* Using std::shared_ptr ensures safe ownership transfer without
* exposing references to internal storage.
*/
virtual std::shared_ptr<T> pop() = 0;
/**
* @brief Attempts to remove the top element and store it in `value`.
*
* @param value Reference where the popped value will be stored.
* @return true if an element was successfully popped, false if the stack was empty.
*
* Marked [[nodiscard]] to prevent ignoring the result of the operation.
*/
[[nodiscard]] virtual bool tryPop(T& value) = 0;
/**
* @brief Attempts to remove the top element and return it.
*
* @return Shared pointer to the removed element, or nullptr if the stack is empty.
*
* This overload avoids the need for an output parameter.
*/
[[nodiscard]] virtual std::shared_ptr<T> tryPop() = 0;
/**
* @brief Checks whether the stack is empty.
*
* @return true if the stack contains no elements.
*
* Note: In concurrent contexts, the result is only a snapshot
* and may become outdated immediately after the call.
*/
[[nodiscard]] virtual bool isEmpty() const = 0;
/**
* @brief Returns the number of elements in the stack.
*
* @return Current size of the stack.
*
* Note: Like isEmpty(), this value may be approximate in highly concurrent scenarios.
*/
[[nodiscard]] virtual size_t getSize() const = 0;
/**
* @brief Removes all elements from the stack.
*
* The exact synchronization guarantees depend on the implementation.
*/
virtual void clear() = 0;
};