File 1564-snmp-Types-and-specs-for-snmp_index-delete... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1564-snmp-Types-and-specs-for-snmp_index-delete-1-2.patch of Package erlang (Revision 44321c08784c0bcdc6b5f65725943eda)

Currently displaying revision 44321c08784c0bcdc6b5f65725943eda , Show latest

From 5af3fe5ad512f722f582447c190b500c5dc460a1 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Mon, 15 Jan 2024 13:03:09 +0100
Subject: [PATCH 44/67] [snmp] Types and specs for snmp_index:delete/1,2

---
 lib/snmp/doc/src/Makefile           |  1 +
 lib/snmp/doc/src/snmp_index.xml     | 93 +++++++++++++++++++++++++----
 lib/snmp/doc/src/specs.xml          |  1 +
 lib/snmp/src/agent/snmp_generic.erl |  2 +-
 lib/snmp/src/agent/snmp_index.erl   | 30 +++++++++-
 5 files changed, 110 insertions(+), 17 deletions(-)

diff --git a/lib/snmp/doc/src/Makefile b/lib/snmp/doc/src/Makefile
index 564b751c82..90afd67b00 100644
--- a/lib/snmp/doc/src/Makefile
+++ b/lib/snmp/doc/src/Makefile
@@ -62,6 +62,7 @@ SPECS_FILES = \
 	$(SPECDIR)/specs_snmp_framework_mib.xml \
 	$(SPECDIR)/specs_snmp_target_mib.xml \
 	$(SPECDIR)/specs_snmp_generic.xml \
+	$(SPECDIR)/specs_snmp_index.xml \
 	$(SPECDIR)/specs_snmpa.xml
 
 TOP_SPECS_FILE = specs.xml
diff --git a/lib/snmp/doc/src/snmp_index.xml b/lib/snmp/doc/src/snmp_index.xml
index 108266e608..22ccaf45cd 100644
--- a/lib/snmp/doc/src/snmp_index.xml
+++ b/lib/snmp/doc/src/snmp_index.xml
@@ -75,6 +75,81 @@ get_next_pid(Oid, SnmpIndex) ->
 </code>
 </description>
 
+ <datatypes>
+ <datatype>
+ <name name="index"/>
+ <desc>
+	
+	 This type denotes an snmp index structure.
+	
+ </desc>
+ </datatype>
+
+ <datatype>
+ <name name="key_spec"/>
+ 
+ </datatype>
+
+ <datatype>
+ <name name="key_types"/>
+ <desc>
+	This type is used when creating the index structure,
+	and the <c>key()</c> type is used when inserting
+	and deleting items from the structure.
+	If the INDEX column is of type INTEGER, or derived from
+	INTEGER, the corresponding type should be <c>integer</c>. If it
+	is a variable length type (e.g. OBJECT IDENTIFIER, OCTET STRING),
+	the corresponding type should be <c>string</c>. Finally, if the
+	type is of variable length, but with a fixed size restriction
+	(e.g. IpAddress), the corresponding type should be
+	<c>fix_string</c>. 
+	There is no way to propely describe this type in the erlang type
+	language, which is why <c>tuple()</c> was used above.
+	The proper definition looks like: 
+	<c>key_types = type_spec() | {type_spec(), type_spec(), ...}</c>
+ </desc>
+ </datatype>
+
+ <datatype>
+ <name name="type_spec"/>
+ 
+ </datatype>
+
+ <datatype>
+ <name name="key"/>
+ <desc>
+	
+	 This type correlates to the
+	 <seetype marker="#key_types">key_types()</seetype>
+	 type.
+	 If the
+	 <seetype marker="#key_types">key_types()</seetype>
+	 is a single atom, the corresponding <c>key()</c>
+	 is a single type as well, but if the
+	 <seetype marker="#key_types">key_types()</seetype>
+	 is a tuple, <c>key()</c> must be a tuple of the same size.
+	
+	There is no way to propely describe this type in the erlang type
+	language, which is why <c>tuple()</c> was used above.
+	The proper definition looks like: 
+	<c>key() = key_spec() | {key_spec(), key_spec(), ...}</c>
+ </desc>
+ </datatype>
+
+ </datatypes>
+
 <section>
 <title>Common data types</title>
 The following data types are used in the functions below:
@@ -159,29 +234,21 @@ get_next_pid(Oid, SnmpIndex) ->
 </section>
 <funcs>
 <func>
- <name since="">delete(Index) -> true</name>
+ <name name="delete" arity="1" clause_i="1" since=""/>
 <fsummary>Delete an index table</fsummary>
- <type>
- <v>Index = NewIndex = index()</v>
- <v>Key = key()</v>
- </type>
 <desc>
 Deletes a complete index structure (i.e. the ets table
 holding the index). The index can no longer be referenced
- after this call. See the <seeerl marker="#1">warning note</seeerl>
- above.
+	 after this call.
+	 See the <seeerl marker="#1">warning note</seeerl> above.
 </desc>
 </func>
 <func>
- <name since="">delete(Index, Key) -> NewIndex</name>
+ <name name="delete" arity="2" clause_i="1" since=""/>
 <fsummary>Delete an item from the index</fsummary>
- <type>
- <v>Index = NewIndex = index()</v>
- <v>Key = key()</v>
- </type>
 <desc>
 Deletes a key and its value from the index structure.
- Returns a new structure.
+	Returns a new structure.
 </desc>
 </func>
 <func>
diff --git a/lib/snmp/doc/src/specs.xml b/lib/snmp/doc/src/specs.xml
index a8716af906..374bf1c1b0 100644
--- a/lib/snmp/doc/src/specs.xml
+++ b/lib/snmp/doc/src/specs.xml
@@ -5,5 +5,6 @@
 <xi:include href="../specs/specs_snmp_framework_mib.xml"/>
 <xi:include href="../specs/specs_snmp_target_mib.xml"/>
 <xi:include href="../specs/specs_snmp_generic.xml"/>
+ <xi:include href="../specs/specs_snmp_index.xml"/>
 <xi:include href="../specs/specs_snmpa.xml"/>
 </specs>
diff --git a/lib/snmp/src/agent/snmp_generic.erl b/lib/snmp/src/agent/snmp_generic.erl
index 7dd67c3b08..9f740a8b90 100644
--- a/lib/snmp/src/agent/snmp_generic.erl
+++ b/lib/snmp/src/agent/snmp_generic.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1996-2022. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2024. 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.
diff --git a/lib/snmp/src/agent/snmp_index.erl b/lib/snmp/src/agent/snmp_index.erl
index fd2f1c8415..6c92f08cf2 100644
--- a/lib/snmp/src/agent/snmp_index.erl
+++ b/lib/snmp/src/agent/snmp_index.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1997-2023. All Rights Reserved.
+%% Copyright Ericsson AB 1997-2024. 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.
@@ -26,6 +26,13 @@
 	 get_last/1, 
 	 key_to_oid/2]).
 
+-export_type([
+ index/0,
+ key_types/0,
+ key_spec/0,
+ type_spec/0,
+ key/0
+ ]).
 
 -define(VMODULE,"IDX").
 -include("snmp_verbosity.hrl").
@@ -36,6 +43,12 @@
 -define(bad_new(A), ?badarg(new, A)).
 -define(bad_get(A), ?badarg(get, A)).
 
+-opaque index() :: #tab{}.
+-type key_types() :: type_spec() | tuple().
+-type key() :: key_spec() | tuple().
+-type key_spec() :: string() | integer().
+-type type_spec() :: fix_string | string | integer.
+
 
 %%%-----------------------------------------------------------------
 %%% This module implements an SNMP index structure as an ADT.
@@ -121,12 +134,23 @@ insert(#tab{id = OrdSet, keys = KeyTypes} = Tab, Key, Val) ->
 ets:insert(OrdSet, {key_to_oid_i(Key, KeyTypes), Val}),
 Tab.
 
+
+-spec delete(Index) -> true when
+ Index :: index().
+
+delete(#tab{id = OrdSet}) ->
+ ets:delete(OrdSet).
+
+
+-spec delete(Index, Key) -> NewIndex when
+ Index :: index(),
+ Key :: key(),
+ NewIndex :: index().
+
 delete(#tab{id = OrdSet, keys = KeyTypes} = Tab, Key) ->
 ets:delete(OrdSet, key_to_oid_i(Key, KeyTypes)),
 Tab.
 
-delete(#tab{id = OrdSet}) ->
- ets:delete(OrdSet).
 
 key_to_oid(#tab{keys = KeyTypes}, Key) ->
 key_to_oid_i(Key, KeyTypes).
-- 
2.35.3

Places

File 1564-snmp-Types-and-specs-for-snmp_index-delete-1-2.patch of Package erlang (Revision 44321c08784c0bcdc6b5f65725943eda)

Places