New in FileMaker Server: Dispatch Queues
During the “Under the Hood: Claris FileMaker Server and WebDirect” session at Claris Engage on March 26, Claris engineers spoke about the implementation of Apple’s Dispatch Queues in the server script engine. They highlighted improvements in scalability and reliability concerning thread handling when running server-side script sessions in the FileMaker Server Script Engine (FMSE).
Claris implemented a change in FileMaker Server (FMS) 21.1.3 that limits the number of concurrent server-side script sessions on the server. This is because of a major change in how script sessions are launched due to the new implementation of Apple’s open-source Dispatch queue in the FileMaker Server Script Engine. This change has not yet been documented in detail, so we’ll share our research findings to help you better understand it.
What are dispatch queues?
Dispatch queues efficiently manage an app’s tasks, whether they need to happen in order or all at once. It keeps the app performing smoothly by preventing the CPU from getting overloaded with too many tasks running simultaneously.
Claris adopted Apple’s implementation of DispatchQueue, which is available on macOS and Linux, and ported it to Windows.
Here’s the description of Apple’s dispatch queue according to its documentation:
Dispatch queues are FIFO queues to which your application can submit tasks in the form of block objects. Dispatch queues execute tasks either serially or concurrently. Work submitted to dispatch queues executes on a pool of threads managed by the system. Except for the dispatch queue representing your app’s main thread, the system makes no guarantees about which thread it uses to execute a task.
You schedule work items synchronously or asynchronously. When you schedule a work item synchronously, your code waits until that item finishes execution. When you schedule a work item asynchronously, your code continues executing while the work item runs elsewhere.
— Source
More information about Dispatch Queues will be available once Claris Engage’s 2025 sessions are released.
What Changed
Release notes of FMS 21.1.3 (source):
- Over time, the FileMaker Script Engine (FMSE) process caused memory to fill up and performance to slow.
- The Web Publishing Engine (WPE) process failed to restart after updating FileMaker Server.
- FileMaker Server stopped responding after performing a backup or running a scheduled script.
- FileMaker Server stopped responding during heavy traffic.
- FileMaker WebDirect: When text was pasted into a field in the latest versions of Google Chrome or Microsoft Edge, the last character of the pasted text was incorrectly deleted when you clicked somewhere outside of the field.
Unlike the FMS 21.1.4 release notes below, the 21.1.3 release notes do not mention the new limit on concurrent server-side script sessions. I hope these insights help you determine whether you need to modify your application before upgrading to 21.1.3 or 21.1.4.
- When cached in a certain access order, field definitions were incorrectly applied for users who subsequently read from the cache. Users with limited access privileges could then experience empty related fields, value lists, indexes, and an error code 9 (“Insufficient privileges”) when clicking in these fields. Claris has now reproduced this issue and verified that it no longer occurs in this release.
- Windows: The number of simultaneous FileMaker Script Engine sessions could not exceed the number of CPU cores allocated to the Windows environment. Now, the maximum number of simultaneous sessions is 50.
Previous vs. New Behavior:
In FileMaker Server versions prior to 21.1.3, the script engine would trigger as many scripts as called simultaneously, even if it is clear that they might overload the server’s resources, especially the CPU. This is something you can easily test for yourself on your server with our Punisher tool on a server running FMS <21.1.3.
In FileMaker Server 21.1.3, the server-side scripting engine will only run script sessions up to a limit that the server’s hardware resources can handle. The maximum number of parallel script sessions allowed is 5, or the total number of CPU cores on the server, whichever is greater. In other words, if the server has more than 5 CPU cores, the maximum number of parallel sessions will equal the number of CPU cores; otherwise, it’s limited to 5.
FileMaker Server 21.1.4 raised the maximum number of parallel script sessions from 5 to 50.
In FileMaker Server 21.1.3, the maximum number of parallel script sessions allowed is the greater of 5 or the total number of CPU cores on the server. With FMS 21.1.4, that maximum increases from 5 to 50.
To see this in action on your server, try running more script sessions than the server’s number of cores. You will observe that the execution will only begin for a maximum of x script calls, where the following calculation determines x:
FMS 21.1.3: max(5 ; number of cores).
FMS 21.1.4: max(50 ; number of cores).
What about the AllowPSOS configuration setting?
The following notes were included in this knowledge base article:
Note: The AllowPSoS setting does not control this behavior.
Recommendations:
To ensure system stability, it is advised to limit active clients to 40 – 45 simultaneous sessions. Exceeding 50 may result in delays, memory overload, or session hangs.
Based on these notes, Claris advises capping the active server-side script sessions at 40 or 45. This limitation is not easily achievable. If you modify the AllowPSOS (or ScriptSessions setting) to 45, it will stop the 46th active server-side script session from executing; you’ll get FileMaker error “812 Exceeded host’s capacity.”
C:\Users\Administrator>fmsadmin get serverprefs AllowPSOS
AllowPSOS = 100 [default: 100, range: 0-500]
C:\Users\Administrator>fmsadmin get serverconfig ScriptSessions
ScriptSessions = 100 [default: 100, range: 0-500]Keep the AllowPSOS setting at 100 or above. I don’t recommend changing it based on the changes described in this blog.
Can I change the number of parallel script sessions on 21.1.3 or 21.1.4?
Unfortunately, it isn’t possible to change the maximum number of parallel script sessions on 21.1.3 through a configuration parameter or a feature flag, nor can you disable this new behavior to revert to the old one. Using Soliant’s deep knowledge of FileMaker Server, we made modifications to get the script engine to support any number of parallel sessions by forcing the expansion of the dispatch queue size to a number that we set. In our test of this modification, we ran 20 parallel server-side script sessions on FMSE (we were limited to 5 before these modifications).
Does this impact the Data API?
The new dispatch queue introduced in FMS 21.1.3 also limits scripts run via the “Perform Script on Server” (PSOS) step on the Data API in the same way as described above. “Perform script” runs scripts in the Data API script engine, not in the script engine on the primary machine (FMSE).
Does this impact server-side script schedules?
Yes, in the same way as PSOS sessions.
Does this impact the OData API?
Yes, in the same way as PSOS sessions.
Unlike the Data API, OData does not have its own scripting engine. Scripts executed on the OData API will run on the server-side scripting engine of the primary machine (FMSE). You can read more about this in Wim Decorte’s blog post here.
Heads up: Read this before upgrading to 21.1.3 or 21.1.4
This new FIFO dispatch queue for script sessions puts all server-side scripts (PSoS, server schedules, OData API) into a single queue with a specific concurrency limit. For example, if your server’s limit is 5, 3 running script schedules will use three slots and keep only two available for PSoS calls. This is less of a concern on 21.1.4 because its maximum is at least 50.
This is different from before, where the server would attempt to run all received server-side script calls concurrently right up to the maximum number allowed by your “scriptsessions” configuration. When this new, often lower, limit is hit, scripts simply wait their turn. The big unknown is performance – it might speed things up overall if your server was previously overloaded, but individual scripts could certainly get stuck waiting longer in line. The main risk here? Long-running scheduled scripts or PSoS calls can hog all the available slots, blocking everything else until they finish, which really highlights why having control over that queue limit is very important in 21.1.3.
Another thing to note here is that the server-side script sessions awaiting execution won’t appear in the server’s client list until it’s their turn. If you attempt to run more scripts than your server’s limit allows, you’ll find that the access log only shows logs for the running scripts and not those in the queue. This method helps reduce the server’s load by minimizing open connections, but it’s good to always be aware of this behavior.
Finally, if server-side script schedules are getting queued because the available slots are full, they will not be executed at the expected time, which can lead to unpredictability in the execution of your server-side scripts.
Concluding Thoughts
After some research, I found indications in FMS 21.1.3 that might suggest that the same Dispatch Queue implementation might be used later for other functionality. The design of dispatch queues permits multiple queues to operate simultaneously. This functionality allows Claris to develop asynchronous features more efficiently on this solid foundation. This looks like a precursor to more interesting features in the future, such as asynchronous script steps.
What do you think about this change? What new asynchronous functionality would you like to see on the FileMaker platform?
Your Next Steps in FileMaker
Our FileMaker consulting team pays close attention to Claris announcements and insights like these to help our clients stay on top of all that’s possible with their Claris solution. If you’d like to speak with one of our technical consultants to learn how we can help you improve, modernize, or integrate your FileMaker application, contact us today.
