You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/usage/FileLock.md
+25-12Lines changed: 25 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,26 +24,32 @@ Optionally, a full exclusive and continuous pessimistic locking mode is availabl
24
24
You can switch between the default optimistic mode and the pessimistic exclusive lock mode.
25
25
26
26
Steps:
27
-
1. Open the `basic.mvbasic.json` file in your online editing project.
28
-
2. Add or modify the property:
27
+
28
+
1. Open the `basic.mvbasic.json` file in your online editing project.
29
+
2. Add or modify the property:
29
30
```json
30
31
{
31
32
"file_lock_state": "ON"// or "OFF" (default optimistic)
32
33
}
33
34
```
34
-
3. Save the configuration file.
35
-
4. Reopen the BASIC program file for the setting to take effect.
35
+
3. Save the configuration file.
36
+
4. Reopen the BASIC program file for the setting to take effect.
36
37
37
38
Meaning:
39
+
38
40
-`ON`: Enables **pessimistic exclusive locking**. When a BASIC file is opened, an exclusive lock is held for the entire edit session. Other users attempting to open the same file receive a message: `This file is locked by another user.`
41
+
39
42
-`OFF` (default / if omitted): Enables **optimistic locking**. Multiple users can open the same file.
Pessimistic locking assumes conflicts are likely. A lock is acquired when the file is opened and retained for the full editing session until the editor is closed or the file is otherwise released. This prevents others from opening the file.
44
47
45
48
Continuous locks can:
49
+
50
+
46
51
- Block other developers for long periods.
52
+
47
53
- Increase the risk of stale locks if the editor crashes. In this case, the extension attempts cleanup, but external factors can interfere.
48
54
49
55
**When File is Already Locked:**
@@ -59,36 +65,42 @@ The file open operation will be aborted, and the file will not open in the edito
In optimistic mode you edit a local copy without holding a server lock. The extension:
68
+
62
69
- Acquires a short READ/validation lock/check when opening.
63
70
- Releases it immediately after obtaining a clean copy.
64
71
- Performs a conflict/lock check before saving (and may perform lightweight checks when an edit is made or when regaining focus) to ensure no exclusive lock is currently held elsewhere.
65
72
66
73
Advantages:
74
+
67
75
- Minimizes lock contention.
68
76
- Improves scalability with many users.
69
77
- Reduces risk of lingering locks after network issues.
70
78
71
79
Risk:
80
+
72
81
- Another user or external process could modify the server copy between your open and save. Your save then overwrites their changes (last-writer-wins) without merge.
73
82
74
83
Currently MVVS does **not** perform an automatic diff/merge or modification timestamp comparison before overwrite.
75
84
76
85
---
77
86
### Save Workflow (Step-by-Step)
78
87
Optimistic Mode (`file_lock_state` = OFF):
79
-
1. the user triggers Save in VS Code.
80
-
2. The extension performs an optimistic conflict/lock check, and attempts a short WRITE or validation lock.
81
-
3. If the acquisition/check fails, a warning displays and the save is aborted. The remote file stays unchanged.
82
-
4. If the check succeeds, a local copy is uploaded and the remote content is replaced.
83
-
5. Any temporary lock is released immediately.
88
+
89
+
1. the user triggers Save in VS Code.
90
+
2. The extension performs an optimistic conflict/lock check, and attempts a short WRITE or validation lock.
91
+
3. If the acquisition/check fails, a warning displays and the save is aborted. The remote file stays unchanged.
92
+
4. If the check succeeds, a local copy is uploaded and the remote content is replaced.
93
+
5. Any temporary lock is released immediately.
84
94
85
95
Exclusive Mode (`file_lock_state` = ON):
86
-
1. The file already has an exclusive lock from open.
87
-
2. the user triggers Save and the write proceeds directly while the existing lock guarantees exclusivity.
88
-
3. The lock is released when the editor/file is closed or project is unloaded.
96
+
97
+
1. The file already has an exclusive lock from open.
98
+
2. the user triggers Save and the write proceeds directly while the existing lock guarantees exclusivity.
99
+
3. The lock is released when the editor/file is closed or project is unloaded.
89
100
90
101
---
91
102
### Best Practices for Teams
103
+
92
104
- Use `file_lock_state = ON` for highly critical or frequently contended programs where overwrites are unacceptable.
93
105
- Use the default optimistic mode for general development to keep collaboration fluid.
94
106
- Communicate when editing critical programs to avoid surprise overwrites (optimistic) or prolonged locks (exclusive).
@@ -108,6 +120,7 @@ Click Okay to overwrite the file.
108
120
**User Actions & Outcomes:**
109
121
110
122
**Click Overwrite (Okay):**
123
+
111
124
- The file will be overwritten on the server, and you will see a confirmation message:
0 commit comments