feature: add ngx.shared.DICT.flush_expired_tail for opportunistic cleanup

README.markdown

@@ -4047,6 +4047,7 @@ Nginx API for Lua
 * [ngx.shared.DICT.expire](#ngxshareddictexpire)
 * [ngx.shared.DICT.flush_all](#ngxshareddictflush_all)
 * [ngx.shared.DICT.flush_expired](#ngxshareddictflush_expired)
+* [ngx.shared.DICT.flush_expired_tail](#ngxshareddictflush_expired_tail)
 * [ngx.shared.DICT.get_keys](#ngxshareddictget_keys)
 * [ngx.shared.DICT.capacity](#ngxshareddictcapacity)
 * [ngx.shared.DICT.free_space](#ngxshareddictfree_space)
@@ -7318,6 +7319,7 @@ The resulting object `dict` has the following methods:
 * [expire](#ngxshareddictexpire)
 * [flush_all](#ngxshareddictflush_all)
 * [flush_expired](#ngxshareddictflush_expired)
+* [flush_expired_tail](#ngxshareddictflush_expired_tail)
 * [get_keys](#ngxshareddictget_keys)
 * [capacity](#ngxshareddictcapacity)
 * [free_space](#ngxshareddictfree_space)
@@ -7814,6 +7816,25 @@ See also [ngx.shared.DICT.flush_all](#ngxshareddictflush_all) and [ngx.shared.DI
 
 [Back to TOC](#nginx-api-for-lua)
 
+ngx.shared.DICT.flush_expired_tail
+----------------------------------
+
+**syntax:** *flushed = ngx.shared.DICT:flush_expired_tail(max_count)*
+
+**context:** *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*, ssl_client_hello_by_lua**
+
+Scans from the least recently used end of the dictionary's LRU queue, freeing expired items and skipping items without an expiration. Stops at the first item with an expiration time in the future, after freeing `max_count` items, or when the queue ends. Returns the number of items freed.
+
+The required `max_count` argument must be a positive integer no greater than the maximum C `int` value (normally 2147483647). Zero does not mean unlimited.
+
+The expiration check and removal are atomic with respect to other shared dictionary operations. This method does not move surviving items in the LRU queue.
+
+Unlike [flush_expired](#ngxshareddictflush_expired), this method does not scan past an item with an expiration time in the future. Expired items behind such an item may remain indefinitely; applications needing to reclaim those items should also arrange another cleanup mechanism, such as occasional calls to `flush_expired`.
+
+The limit bounds the number of items freed, not the number inspected or elapsed time. Skipping items without an expiration can require scanning the entire dictionary. Removing an expired list also frees all its elements while holding the dictionary lock; one list counts as one item towards `max_count`.
+
+[Back to TOC](#nginx-api-for-lua)
+
 ngx.shared.DICT.get_keys
 ------------------------
 

src/ngx_http_lua_shdict.c

@@ -21,6 +21,9 @@ static ngx_int_t ngx_http_lua_shdict_lookup(ngx_shm_zone_t *shm_zone,
     ngx_uint_t hash, u_char *kdata, size_t klen,
     ngx_http_lua_shdict_node_t **sdp);
 static int ngx_http_lua_shdict_flush_expired(lua_State *L);
+static int ngx_http_lua_shdict_flush_expired_tail(lua_State *L);
+static int ngx_http_lua_shdict_flush_expired_helper(lua_State *L,
+    int tail_only);
 static int ngx_http_lua_shdict_get_keys(lua_State *L);
 static int ngx_http_lua_shdict_lpush(lua_State *L);
 static int ngx_http_lua_shdict_rpush(lua_State *L);
@@ -317,7 +320,7 @@ ngx_http_lua_inject_shdict_api(ngx_http_lua_main_conf_t *lmcf, lua_State *L)
         lua_createtable(L, 0, lmcf->shdict_zones->nelts /* nrec */);
                 /* ngx.shared */
 
-        lua_createtable(L, 0 /* narr */, 22 /* nrec */); /* shared mt */
+        lua_createtable(L, 0 /* narr */, 23 /* nrec */); /* shared mt */
 
         lua_pushcfunction(L, ngx_http_lua_shdict_lpush);
         lua_setfield(L, -2, "lpush");
@@ -337,6 +340,9 @@ ngx_http_lua_inject_shdict_api(ngx_http_lua_main_conf_t *lmcf, lua_State *L)
         lua_pushcfunction(L, ngx_http_lua_shdict_flush_expired);
         lua_setfield(L, -2, "flush_expired");
 
+        lua_pushcfunction(L, ngx_http_lua_shdict_flush_expired_tail);
+        lua_setfield(L, -2, "flush_expired_tail");
+
         lua_pushcfunction(L, ngx_http_lua_shdict_get_keys);
         lua_setfield(L, -2, "get_keys");
 
@@ -393,6 +399,20 @@ ngx_http_lua_shdict_get_zone(lua_State *L, int index)
 
 static int
 ngx_http_lua_shdict_flush_expired(lua_State *L)
+{
+    return ngx_http_lua_shdict_flush_expired_helper(L, 0);
+}
+
+
+static int
+ngx_http_lua_shdict_flush_expired_tail(lua_State *L)
+{
+    return ngx_http_lua_shdict_flush_expired_helper(L, 1);
+}
+
+
+static int
+ngx_http_lua_shdict_flush_expired_helper(lua_State *L, int tail_only)
 {
     ngx_queue_t                     *q, *prev, *list_queue, *lq;
     ngx_http_lua_shdict_node_t      *sd;
@@ -404,10 +424,15 @@ ngx_http_lua_shdict_flush_expired(lua_State *L)
     ngx_rbtree_node_t               *node;
     uint64_t                         now;
     int                              n;
+    lua_Number                       limit;
     ngx_http_lua_shdict_list_node_t *lnode;
 
     n = lua_gettop(L);
 
+    if (tail_only && n != 2) {
+        return luaL_error(L, "expecting 2 arguments, but saw %d", n);
+    }
+
     if (n != 1 && n != 2) {
         return luaL_error(L, "expecting 1 or 2 argument(s), but saw %d", n);
     }
@@ -419,7 +444,16 @@ ngx_http_lua_shdict_flush_expired(lua_State *L)
         return luaL_error(L, "bad user data for the ngx_shm_zone_t pointer");
     }
 
-    if (n == 2) {
+    if (tail_only) {
+        limit = luaL_checknumber(L, 2);
+        if (!(limit >= 1 && limit <= INT_MAX) || limit != (int) limit) {
+            return luaL_argerror(L, 2,
+                                 "positive integer within int range expected");
+        }
+
+        attempts = (int) limit;
+
+    } else if (n == 2) {
         attempts = luaL_checkint(L, 2);
     }
 
@@ -472,6 +506,9 @@ ngx_http_lua_shdict_flush_expired(lua_State *L)
             if (attempts && freed == attempts) {
                 break;
             }
+
+        } else if (tail_only && sd->expires != 0) {
+            break;
         }
 
         q = prev;