Mistake on this page?
Report an issue in GitHub or email us
SocketStats.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2018 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef SOCKET_STATS_H
18 #define SOCKET_STATS_H
19 
20 #include "platform/SingletonPtr.h"
21 #include "platform/PlatformMutex.h"
22 #include "netsocket/Socket.h"
23 #include "SocketAddress.h"
24 #include "hal/ticker_api.h"
25 
26 #ifndef MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT
27 #define MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT 10
28 #endif
29 
30 /** Enum of socket states
31  *
32  * Can be used to specify current state of socket - open, closed, connected or listen.
33  *
34  * @enum socket_state
35  */
36 typedef enum {
37  SOCK_CLOSED, /**< Socket is closed and does not exist anymore in the system */
38  SOCK_OPEN, /**< Socket is open but not associated to any peer address */
39  SOCK_CONNECTED, /**< Socket is associated to peer address, either by connect() or sendto()/recvfrom() calls */
40  SOCK_LISTEN, /**< Socket is listening for incoming connections */
41 } socket_state;
42 
43 /** Structure to parse socket statistics
44  */
45 typedef struct {
46  Socket *reference_id; /**< Used for identifying socket */
47  SocketAddress peer; /**< Last associated peername of this socket (Destination address) */
48  socket_state state; /**< State of this socket */
49  nsapi_protocol_t proto; /**< Specifies a protocol used with socket */
50  size_t sent_bytes; /**< Data sent through this socket */
51  size_t recv_bytes; /**< Data received through this socket */
52  us_timestamp_t last_change_tick;/**< osKernelGetTick() when state last changed */
54 
55 /** SocketStats class
56  *
57  * Class to get the network socket statistics
58  */
59 class SocketStats {
60 public:
61 
62 #if !defined(DOXYGEN_ONLY)
63  /** Create a socket statistics object
64  *
65  * Application users must not create class objects.
66  * Entities reporting network statistics create the class object.
67  * Application can fetch network statistics using static `mbed_stats_socket_get_each` API
68  * without creating an object.
69  */
70  constexpr SocketStats() = default;
71 #endif
72  /**
73  * Fill the passed array of structures with the socket statistics for each created socket.
74  *
75  * @param stats A pointer to an array of mbed_stats_socket_t structures to fill
76  * @param count The number of mbed_stats_socket_t structures in the provided array
77  * @return The number of mbed_stats_socket_t structures that have been filled.
78  * If the number of sockets on the system is less than or equal to count,
79  * it will equal the number of sockets created (active or closed).
80  * If the number of sockets on the system is greater than count,
81  * it will equal count.
82  */
83  static size_t mbed_stats_socket_get_each(mbed_stats_socket_t *stats, size_t count);
84 
85 #if !defined(DOXYGEN_ONLY)
86  /** Add entry of newly created socket in statistics array.
87  * API used by socket (TCP or UDP) layers only, not to be used by application.
88  *
89  * @param reference_id ID to identify socket in data array.
90  *
91  * @Note: The entry in the array is maintained even after the socket is closed.
92  * The entry is overwritten for sockets that were closed first, in case
93  * the socket creation count exceeds `MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT`.
94  *
95  */
96  void stats_new_socket_entry(Socket *reference_id);
97 
98  /** Updates the state of the socket and records `tick_last_change`.
99  * API used by socket (TCP or UDP) layers only, not to be used by application.
100  *
101  * @param reference_id ID to identify socket in data array.
102  * @param state Parameter to update the current state of the socket.
103  *
104  */
105  void stats_update_socket_state(const Socket *reference_id, socket_state state);
106 
107  /** Update the peer information of the socket.
108  * API used by socket (TCP or UDP) layers only, not to be used by application.
109  *
110  * @param reference_id ID to identify socket in data array.
111  * @param peer Parameter to update destination peer information.
112  *
113  */
114  void stats_update_peer(const Socket *reference_id, const SocketAddress &peer);
115 
116  /** Update socket protocol.
117  * API used by socket (TCP or UDP) layers only, not to be used by application.
118  *
119  * @param reference_id ID to identify socket in data array.
120  * @param proto Parameter to update the protocol type of socket.
121  *
122  */
123  void stats_update_proto(const Socket *reference_id, nsapi_protocol_t proto);
124 
125  /** Update bytes sent on socket, which is cumulative count per socket.
126  * API used by socket (TCP or UDP) layers only, not to be used by application.
127  *
128  * @param reference_id ID to identify socket in data array.
129  * @param sent_bytes Parameter to append bytes sent over the socket.
130  *
131  */
132  void stats_update_sent_bytes(const Socket *reference_id, size_t sent_bytes);
133 
134  /** Update bytes received on socket, which is cumulative count per socket
135  * API used by socket (TCP or UDP) layers only, not to be used by application.
136  *
137  * @param reference_id ID to identify socket in data array.
138  * @param recv_bytes Parameter to append bytes the socket receives.
139  *
140  */
141  void stats_update_recv_bytes(const Socket *reference_id, size_t recv_bytes);
142 
143 #if MBED_CONF_NSAPI_SOCKET_STATS_ENABLED
144 private:
145  static mbed_stats_socket_t _stats[MBED_CONF_NSAPI_SOCKET_STATS_MAX_COUNT];
146  static SingletonPtr<PlatformMutex> _mutex;
147  static uint32_t _size;
148 
149  /** Internal function to scan the array and get the position of the element in the list.
150  *
151  * @param reference_id ID to identify the socket in the data array.
152  *
153  */
154  int get_entry_position(const Socket *reference_id);
155 #endif
156 #endif
157 };
158 
159 #if !MBED_CONF_NSAPI_SOCKET_STATS_ENABLED
161 {
162  return 0;
163 }
164 
165 inline void SocketStats::stats_new_socket_entry(Socket *)
166 {
167 }
168 
169 inline void SocketStats::stats_update_socket_state(const Socket *, socket_state)
170 {
171 }
172 
173 inline void SocketStats::stats_update_peer(const Socket *, const SocketAddress &)
174 {
175 }
176 
177 inline void SocketStats::stats_update_proto(const Socket *, nsapi_protocol_t)
178 {
179 }
180 
181 inline void SocketStats::stats_update_sent_bytes(const Socket *, size_t)
182 {
183 }
184 
185 inline void SocketStats::stats_update_recv_bytes(const Socket *, size_t)
186 {
187 }
188 #endif // !MBED_CONF_NSAPI_SOCKET_STATS_ENABLED
189 
190 #endif
nsapi_protocol_t proto
Specifies a protocol used with socket.
Definition: SocketStats.h:49
SocketAddress class.
size_t recv_bytes
Data received through this socket.
Definition: SocketStats.h:51
us_timestamp_t last_change_tick
osKernelGetTick() when state last changed
Definition: SocketStats.h:52
uint64_t us_timestamp_t
A us timestamp stored in a 64 bit integer.
Definition: ticker_api.h:39
SocketAddress peer
Last associated peername of this socket (Destination address)
Definition: SocketStats.h:47
Abstract Socket interface.
SocketAddress class.
Definition: SocketAddress.h:36
Socket interface.
Definition: Socket.h:39
static size_t mbed_stats_socket_get_each(mbed_stats_socket_t *stats, size_t count)
Fill the passed array of structures with the socket statistics for each created socket.
Definition: SocketStats.h:160
SocketStats class.
Definition: SocketStats.h:59
socket_state state
State of this socket.
Definition: SocketStats.h:48
size_t sent_bytes
Data sent through this socket.
Definition: SocketStats.h:50
Structure to parse socket statistics.
Definition: SocketStats.h:45
Socket * reference_id
Used for identifying socket.
Definition: SocketStats.h:46
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.