CA-422282 Fix race condition about xenops cache

There is race condition about vm cache between pool_migrate_complete
and VM event.
In the cross-pool migration case, it is designed to create vm with
power_state Halted in XAPI db. In pool_migrate_complete, add_caches
create an empty xenops_chae for the VM, then refresh_vm compares the
cache powerstate None with its real state Running to update the
right powerstate to XAPI db.
In the fail case, it is found that:
-> VM event 1 update_vm
-> pool_migrate_complete add_caches (cache power_state None)
-> pool_migrate_complete refresh_vm
-> VM event 1 update cache (cache power_state Running)
-> VM event 2 update_vm (Running <-> Running, XAPI DB not update)
When pool_migrate_complete add_caches, the cache update of previous
VM event 1 breaks the design intention.

This PR Add a new interface add_caches_and_refresh to make the
procedure race-free.
1. Wait for barrier - ensure all in-flight events complete
2. Suppress + add_caches - prevent new events
3. Refresh

Signed-off-by: Changlei Li <changlei.li@cloud.com>

Author: changlei-li

ocaml/xapi/xapi_vm_migrate.ml

@@ -492,8 +492,7 @@ let pool_migrate_complete ~__context ~vm ~host:_ =
   if Xapi_xenops.vm_exists_in_xenopsd queue_name dbg id then (
     remove_stale_pcis ~__context ~vm ;
     Xapi_xenops.set_resident_on ~__context ~self:vm ;
-    Xapi_xenops.add_caches id ;
-    Xapi_xenops.refresh_vm ~__context ~self:vm ;
+    Xapi_xenops.add_caches_and_refresh queue_name dbg id ;
     Monitor_dbcalls_cache.clear_cache_for_vm ~vm_uuid:id
   ) ;
   (* Reset the state, which will update allowed operations, clear reservations

ocaml/xapi/xapi_xenops.ml

@@ -1924,6 +1924,18 @@ let add_caches id =
       Xenops_cache.register id
   )
 
+let add_caches_and_refresh queue_name dbg id =
+  (* Fix race condition with proper three-step approach:
+     Step 1: Wait for barrier - ensures all in-flight events complete
+             This prevents TOCTOU where an event passes the suppression check
+             but writes to cache after the wipe.
+     Step 2: Suppress + wipe - prevents new events during cache wipe
+     Step 3: Refresh (automatic) - with_suppressed cleanup calls refresh_vm
+             which generates fresh events and waits for barrier
+  *)
+  Events_from_xenopsd.wait queue_name dbg id () ;
+  Events_from_xenopsd.with_suppressed queue_name dbg id (fun () -> add_caches id)
+
 let to_xenops_console_protocol =
   let open Vm in
   function `rfb -> Rfb | `vt100 -> Vt100 | `rdp -> Rfb