Shërbimi Windows në Delphi: Mbyllje e kontrolluar (Graceful Shutdown) me TEvent dhe Stop-Timeout — implementim i saktë

Një Windows Service in Delphi në përditshmëri shpesh duket jo spektakolare: punon në sfond, përpunon punë (jobs), shkruan logs, komunikon me baza të dhënash ose REST-API. Deri sa dikush klikon „Ndalo shërbimin“ – ose vjen një rinisje për shkak të patch-it – dhe shërbimi nuk ndalet siç duhet. Atëherë konzola e shërbimeve tregon për minuta me radhë „Wird beendet…“, shërbimi ngec në statusin Stop Pending, dhe në rastin më të keq procesi përfundohet me forcë. Pikërisht këtu ia vlen ta trajtosh si çështje arkitekturore të vetëdijshme: Mbyllje e kontrolluar e Windows Service në Delphi me një sinjal të qartë të ndalimit, timeoute të përkufizuara dhe thread-e që reagojnë realisht.

Në këtë shkrim nuk bëhet fjalë për internat e framework-ut, por për një model praktik: TEvent si sinjal ndalimi (një objekt sinkronizimi pranë kernel-it nga System.SyncObjs), i kombinuar me një strategji Stop-Timeout që merr në konsideratë si Windows Service Control Manager (SCM, pra komponentën e Windows që start/stop shërbimet) ashtu edhe thread-et e tua të punëtorëve. Përfshin raste tipike kufitare, qasje për debug dhe kur vlen vërtet të shtosh këtë logjikë.

Windows Service in Delphi Mbyllje e kontrolluar në praktikë

Shkaqja më e zakonshme është e thjeshtë: Shërbimi ka të paktën një thread që ngec në një operacion bllokues dhe nuk njeh një rrugë për ndërprerje. Klasikët:

• Petla polling me Sleep: „while not Terminated do Sleep(1000)“. Kur vjen komanda për ndalim, sinjali arrin, por thread-i reagon vetëm pas deri në 1 sekondë (ose 30 sekonda…).
• I/O bllokuese: thirrje për baza të dhënash, kërkesa HTTP, Named Pipes, pritje të sistemit të skedarëve – çdo gjë që „thjesht pret“, pa u kujdesur për një sinjal ndalimi.
• Queue-Consumer pa Wakeup: një worker pret në një queue, por gjatë ndalimit ai nuk zgjohet për të dalë.
• Renditja e locks/Deadlocks: Gjatë ndalimit bëhet „Cleanup“, ndërsa thread-et e tjera mbajnë ende locks. Kjo ndodh shpesh vetëm në rrugën e ndalimit, sepse renditja atje është ndryshe nga në funksionimin normal.

Windows SCM pret që një shërbim të reagojë shpejt ndaj një komande ndalimi dhe të raportojë vazhdimisht statusin e tij (përmes SetServiceStatus; Delphi e kapsulon këtë në komponentën e Service). Nëse pranon një ngjarje ndalimi, por nuk fik mirë thread-et tuaja, procesi mbetet i gjallë – dhe Windows vendos në një moment që „po zgjat tepër“. Rezultati është ose një ndërprerje e fortë, ose një shërbim që ngec në një gjendje të paqartë.

Parimi themelor: Një sinjal ndalimi që e kupton çdo worker

Një Mbyllje e kontrolluar funksionon vetëm nëse ke një sinjal që:

• që mund të vëzhgohet nga të gjitha thread-et relevante,
• të ketë efekt edhe kur ndodhet në gjendje pritjeje që bllokojnë,
• në rrugën e Stop të jetë deterministik (pa „ndoshta do të dalë njëherë“-shpresë),
• të ketë një strategji Timeout të qartë.

In Delphi ist TEvent dafür ein sehr brauchbares Werkzeug: ein Event-Objekt, das intern über Windows-Handles umgesetzt ist (vergleichbar mit CreateEvent/SetEvent). Du kannst es als „Stop requested“-Signal verwenden. Jeder Worker wartet dann nicht einfach blind, sondern wartet „auf Arbeit oder auf Stop“.

Zgjedhja e duhur e TEvent: ManualReset vs. AutoReset

Bei Stop-Signalen willst du üblicherweise Manual Reset (manuell zurücksetzbar): Einmal gesetzt, bleibt das Event „signaled“, bis du es zurücksetzt. Damit ist sichergestellt, dass jeder Thread, der später in eine Wartephase kommt, das Stop-Signal trotzdem erkennt. Auto Reset wäre hier riskant, weil es das Signal nach einem wartenden Thread automatisch zurücksetzt und andere Threads das Stop-Signal verpassen könnten.

Delphi-Service-Lebenszyklus: Ku vjen me të vërtetë Stop

Ein Delphi-Windows- und Linux-Services basiert typischerweise auf TService (VCL/RTL). Der SCM schickt Kommandos (Start, Stop, Pause, Continue). Delphi ruft dann entsprechende Events/Methoden auf (je nach Template z. B. OnStart, OnStop, OnExecute).

E rëndësishme për arkitekturën:

• OnStop nuk është vend për pritje të gjatë pa përditësime të statusit. Është vendi ku nisni shutdown-in anstößt dhe pastaj prisni në mënyrë të kontrolluar – me timeout.
• OnExecute shpesh është një cikël. Nëse aty punon „endlos“, cikli duhet të reagojë ndaj një sinjali Stop.
• Worker-Threads (TThread oder Thread-Pools) müssen auf dasselbe Stop-Signal reagieren, sonst ist der Service logisch gestoppt, aber physisch noch nicht fertig.

Model i pastër: Stop-Event + Join i Worker-ëve + Fallback i fortë

Das praxistaugliche Muster besteht aus vier Schritten:

1. Kërkesa për Stop: Stop-Event setzen, keine neuen Jobs mehr annehmen.
2. Shkaktoni wakeups: Wenn Worker auf Queues oder Sleeps warten, müssen sie „aufwachen“ können (z. B. über Event/Queue-Signal).
3. Mbyllje e rregullt: Worker beenden ihre Loops, schließen Ressourcen (DB-Verbindungen, Dateien, Handles) und melden „fertig“.
4. Timeout und Fallback: Wenn nicht alles rechtzeitig endet, musst du eine Entscheidung treffen: weiter warten (mit Status-Update) oder kontrolliert abbrechen/hart beenden (je nach Risiko).

Der Kern ist: kein Thread darf ausschließlich auf Zeit warten (Sleep) oder ausschließlich auf I/O blockieren, ohne parallel ein Stop-Signal zu berücksichtigen. Stattdessen arbeitest du mit Wartefunktionen, die mehrere Signale berücksichtigen (z. B. „Stop-Event oder Work-Event“), oder du kapselst I/O in Timeouts plus Stop-Checks.

Stop-Timeout: SCM-Timeout vs. shutdown-timeout i juaji

Këtu ndodhin shumica e keqkuptimeve në projekte. Ekzistojnë dy nivele të ndryshme të timeout:

• Pritshmëria e SCM: Windows pret që të raportosh rregullisht përparimin kur je në gjendjen SERVICE_STOP_PENDING. Përndryshe duket sikur je i bllokuar. Delphi merret pjesërisht me këtë, por sapo të bllokohesh për kohë të gjatë, të duhet një strategi se si të mundësosh përditësime të mëtejshme të statusit (ose si të mbash shkurt fazën e ndalimit).
• Timeout-i yt i ndërprerjes (Shutdown): Për shembull, përcakton: „I japim vetes 20 sekonda për të përfunduar pastër punët në proces, pastaj ndërpresim.“ Kjo është një vendim arkitekturor: konsistenca e të dhënave vs. detyrimi për reboot vs. kërkesat operative.

Praktikisht kjo do të thotë: Shërbimi yt duhet të kalojë shpejt në një gjendje ku ai nuk nis më njësi të reja pune, dhe pastaj vetëm pret që puna në proces të përfundojë – por jo pafundësisht. Dhe kjo fazë pritjeje duhet të funksionojë në intervale të shkurtra, në mënyrë që të mund të reagosh dhe, në rast nevoje, të regjistrosh.

Sa gjatë mund të zgjasë ndalimi?

Nuk ka një numër magjik që i përshtatet gjithmonë. Për shumë shërbime biznesi, një diapazon synimi prej 5–30 sekonda është realist: kohë e mjaftueshme për të dhënat „in-flight“, por mjaft e shkurtër për dritaret e patch-it. Nëse shpesh të duhet më shumë kohë, kjo shpesh tregon që përpunon njësi shumë të mëdha në një copë ose që varësitë e jashtme (DB/HTTP) funksionojnë pa timeout.

Implementimi me TEvent: Strukturë që mbetet e qëndrueshme në operim

Një ndërtim i provuar në shërbimin Delphi duket kështu (pa thelluar detajet e framework-ut):

• Një Stop-Event (TEvent, Manual Reset), i cili vendoset gjatë ndalimit.
• Një ose disa Worker-Threads, të cilët në ciklin e tyre kryesor kontrollojnë rregullisht për Stop.
• Opsional një Work-Event ose një Queue, që sinjalizon punën. Worker-ët më pas presin „Work oder Stop“.
• Një Shutdown-Phase, që bën join të Worker-ëve (pra pret deri sa të përfundojnë), por me timeout.

E rëndësishme nuk është nëse përdor TThread, omnithreadlibrary ose një pool tënd, por që Worker-t të mos funksionojnë „të verbër“. Një loop i Worker-it duhet të duket strukturalisht kështu: Pritje për ngjarje(a) → Punë në copa të vogla → Kontrollo Stop midis copave → Lironi burimet pastër.

Kurth: Terminate vetëm nuk mjafton

Shumë threda në Delphi prishen me Terminate. Por kjo është vetëm një flamur. Nëse threda është aktualisht në një API bllokuese, nuk ndodh asgjë menjëherë. Prandaj një Stop-Event i pavarur është kaq i dobishëm: mund ta integroni në thirrjet e pritjes dhe të shkaktoni zgjuarje (wakeups) të synuara.

Kurth: FreeOnTerminate në kontekstin e shërbimit

Në shërbime shpesh shihet FreeOnTerminate := True. Kjo mund të funksionojë, por e vështirëson kontrollin e shutdown-it, sepse shpesh nuk ke më një referencë të pastër për të pritur për përfundimin e thredave dhe për të protokolluar gjendjet e gabimit. Për logjikën e ndaljes të kontrolluar zakonisht është më e qëndrueshme të posedosh thredat në mënyrë eksplizite dhe gjatë shutdown-it të presësh dhe t’i lirësh në mënyrë deterministike.

Operacionet bllokuese: Si t’i bësh të ndalueshme

Pjesa më e vështirë nuk është vetë eventi, por vendet ku shërbimi yt bllokohet. Tre klasa tipike:

1) Sleep/Polling ersetzen: Wait mit Stop-Event

Nëse punon periodikisht („kontrollo çdo 10 sekonda“), mos përdor Sleep(10000), por pris për një event me timeout. Në këtë mënyrë Stop-Event mund ta përfundojë pritjen menjëherë. Kjo redukton latencën e ndalimit dhe parandalon ndjesinë „shërbimi nuk përgjigjet“.

2) Queue-Consumer: Work-Event + Stop-Event kombinieren

Nëse ke një arkitekturë Producer/Consumer (p.sh. punët vendosen në një queue), të duhet një sinjal që zgjon consumer-at. Shpesh është një TEvent i dytë (Work available). Konsumeri pret më pas për dy handle: „Work“ ose „Stop“. Në Stop vendos Stop-Event dhe, nëse nevojitet, edhe Work-Event, në mënyrë që të gjithë consumer-at të dalin garantuar nga pritja.

3) Externe Calls (DB/HTTP): Timeouts und Abbruchpfade

Tek akseset në bazë të të dhënave ose thirrjet HTTP vendoset nëse shërbimi yt ndalet pastër. Për operacionin vlen rregulla: Asnjë thirrje pa timeout. Një timeout nuk është luks, por kusht për kontrollueshmëri. Për më tepër duhet të kontrollosh Stop-in midis fazave të retries/backoff. Përndryshe ke klasikun: „shërbimi nuk ndalet sepse po bën 10 retries me Sleep“.

Në disa biblioteka mund të nxisësh ndërprerje eksplicite (p.sh. ndërprerja e Query). Nëse kjo nuk është e mundur, duhet të konfiguroni timeout-et aq të shkurtra sa të mos tejkalojnë shutdown-timeout-in.

Trajtimi i saktë i ‚Stop Pending‘: statusi, logimi dhe menaxhimi i pritshmërive

Kur një shërbim ndalet, nga pikëpamja e operimit është e rëndësishme të kuptosh ku ngel. Për këtë të duhen dy gjëra:

• Markerë logu në rrugën e Stop: „Stop i kërkuar“, „asnjë punë e re“, „prit për Worker“, „Worker X përfundoi“, „Shutdown përfundoi“.
• Koha e matshme: Sa zgjat ndalimi? Cila fazë konsumon kohë? Shpesh mjafton një masë kohe monotone si GetTickCount64 ose TStopwatch (monotone = e paprekur nga ndryshimet e kohës së sistemit).

Nëse në rrugën e ndalimit shkruan vetëm një hyrje logu „Duke ndaluar…“, debugimi në terren mbetet një lojë me hamendje. Në operimin e shërbimit, loget shpesh janë e vetmja gjë që merr pa ndërveprim.

Cilat loge janë vërtet të dobishme në shërbimet?

• PID-i i shërbimit, koha e nisjes, Version/Build (pa overhead të tepruar).
• Numri i worker-ëve aktivë, numri i punëve në përpunim.
• Varësitë e jashtme aktive: „thirrje DB po ekzekutohet“, „kërkesë HTTP po ekzekutohet“, „flush i skedarit po ekzekutohet“ (vetëm i agreguar, jo çdo detaj).
• Koha maksimale e ndalimit e tejkaluar: cilët worker janë ende të bllokuar?

Gjetja e gabimeve në terren: bëje të riprodhueshme në vend të hamendësimeve

Problemet e ndalimit shfaqen shpesh vetëm në prodhim: ngarkesë tjetër, latenza të ndryshme, të drejta të ndryshme, dritare patch-esh të ndryshme. Disa leva të provuara praktikisht:

Testo shërbimin nën kushte të kontrolluara

• Ndalesa gjatë përpunimit aktiv (jo në idle).
• Ndalesa gjatë një ndërprerjeje të jashtme: DB e pakohë e paqasshme, endpoint HTTP i ngadalësuar, fileshare i zhdukur.
• Ndalesa menjëherë pas nisjes (race-conditions: worker-ët ende në ndërtim).

Event Viewer dhe Service Control Manager Signale

Windows shkruan ngjarje shërbimi, por ato shpesh janë të përgjithshme. Më mirë është që shërbimi yt ta shkruajë vetë në një skedar logu ose në Windows Event Log. E rëndësishme: regjistrimi duhet të funksionojë ende gjatë rrugës së ndalimit. Nëse lirosh mjetet e regjistrimit përpara kohe gjatë mbylljes ose flush bllokohet, humbni pikërisht gjurmët vendimtare.

Bëj të dukshëm thread-et e ngecura

Nëse shikon përsëritshëm „Stop Timeout“, ia vlen të shikosh gjendjet e fijeve të ekzekutimit (p.sh. me debugger/Procdump në mjedis testimi). Shpesh gjen një fije në gjendje pritjeje mbi një handle që kurrë nuk sinjalizohet, ose një thirrje rrjeti pa timeout. Rregullimi rrallë është „më shumë Sleep“, por një rrugë e pastër për ndërprerje.

Kur ia vlen vërtet përpjekja?

Një shërbim minimalist që ka vetëm një timer dhe nuk ka varësi të jashtme mund të ndalet ndonjëherë „thjesht“. Por sapo të përmbushet ndonjë prej këtyre kushteve, një mbyllje e kontrolluar (Graceful Shutdown) ia vlen pothuajse gjithmonë:

• Shërbimi përpunon detyra me efekte anësore (shkrim skedarësh, transaksione DB, thirrje API).
• Ekzistojnë më shumë fije ekzekutimi ose një pool.
• Shërbimi varet nga burime rrjeti (DB, REST, broker mesazhesh, fileshare).
• Operimi kërkon dritare mirëmbajtjeje të planifikueshme (ristartime, përditësime, failover).

Vlera shtesë nuk është „eleganca“, por siguria e operimit: më pak ndërprerje të ashpra të procesit, më pak gjendje të ndërmjetme inkonsistente, më pak ndërhyrje manuale.

Rreziqet praktike: çfarë shkon keq gjatë mbylljes

1) Ndalesa është vendosur, por detyra të reja përsëri hyjnë

Nëse pranon punë hyrëse (p.sh. përmes socket, trigger skedari, timer), duhet që në rrugën e ndalimit së pari të ndalosh pranimin e punës së re: mbyll listener-in, çaktivizo timer-in, ndalo scheduler-in. Përndryshe do të vraposh pas përfundimit, sepse detyra të reja vazhdojnë të nisin.

2) Pastrimi bllokohet (Flush, Close, Finalize)

„Vetëm të bëj shpejt flush gjithçka“ mund të jetë i rrezikshëm në kontekstin e shërbimit, nëse destinacioni (disk rrjeti, log i largët, DB) momentalisht është i ngatërruar. Prandaj: pastrim po, por me kohë të kufizuar. Nëse duhet, duhet të vendosësh se cilat të dhëna i humb në memorie, në vend që të bllokosh të gjithë ndalimin.

3) Bllokimet dhe renditja

Beim Stop greifst du häufig auf dieselben Datenstrukturen zu wie die Worker (Queues, Caches, States). Wenn der Stop-Thread Locks hält und dann auf Worker-Ende wartet, während Worker denselben Lock brauchen, hast du einen Stop-Deadlock. Gegenmittel: Lock-Hold-Zeiten klein halten, im Stop-Pfad nicht „unter Lock warten“, klare Reihenfolge definieren.

4) Nebenläufigkeit beim doppelten Stop

In der Praxis kann Stop mehrfach getriggert werden (z. B. Stop + Shutdown, oder Stop kommt erneut). Dein Stop-Pfad sollte idempotent sein: Stop-Event setzen ist okay, aber doppelte Join/Free-Logik muss sauber geschützt werden (z. B. über ein Atomik-Flag).

Operativer Blick: Was Admins und IT-Leads vom Service erwarten

Für Betrieb und Administration zählt am Ende nicht, wie „schön“ der Code ist, sondern ob der Dienst:

• bei Stop verlässlich endet (planbar, ohne Hänger),
• bei Stop keine inkonsistenten Daten produziert (z. B. halbe Dateien, offene Transaktionen),
• im Fehlerfall brauchbare Logs liefert,
• bei Wartungsfenstern und Deployments berechenbar ist.

Das ist auch der Grund, warum das Thema Stop-Timeout nicht nur „Entwicklerkram“ ist: Es beeinflusst Patchzyklen, Recovery-Zeiten und die Frage, ob automatisierte Deployments überhaupt möglich sind.

Konkrete Leitplanken für ein robustes Shutdown-Design

Wenn du das Thema pragmatisch standardisieren willst, haben sich diese Leitplanken bewährt:

• Ein globales Stop-Event, Manual Reset, früh im Service-Lebenszyklus erstellt, spät freigegeben.
• Kein Sleep in Worker-Loops ohne Stop-fähige Alternative (Wait mit Timeout).
• Alle externen Calls mit Timeouts (DB, HTTP, Fileshares). Timeouts so wählen, dass sie in deinen Shutdown-Timeout passen.
• Stop-Timeout als Konfiguration (z. B. in INI/Registry), damit Betrieb reagieren kann, ohne neu zu kompilieren.
• Stufenmodell: Erst graceful (laufende Jobs zu Ende), dann optional „soft abort“ (keine neuen Schritte), dann harter Exit als letzter Ausweg.
• Gute Stop-Logs mit Phasen und Zeitmessung.

Fazit: TEvent + Stop-Timeout ist kein Luxus, sondern Steuerbarkeit

Ein hängender Stop ist selten ein Einzelfehler – meist ist es ein Architekturloch: Arbeit läuft in Threads oder blockierenden Calls, die kein gemeinsames Stop-Signal kennen. Mit einem klaren Stop-Event (TEvent, Manual Reset), stop-fähigen Waits statt Sleep, konsequenten Timeouts für externe Abhängigkeiten und einem definierten Shutdown-Timeout bekommst du einen Service, der im Alltag berechenbar ist.

Der Code lohnt sich besonders, wenn dein Service in Produktionsumgebungen mit Wartungsfenstern, automatisierten Deployments oder kritischen Seiteneffekten arbeitet. Dann ist „Graceful Shutdown“ nicht Kosmetik, sondern ein Baustein für stabilen Betrieb und weniger Eskalationen beim nächsten Reboot.

Wenn du euren Stop-Pfad einmal sauber aufsetzen oder einen bestehenden Delphi-Service auf robuste Shutdown-Logik und Betriebssicherheit überprüfen willst, ist ein technischer Sparrings-Call oft der schnellste Weg zu klaren Maßnahmen: Kontakt aufnehmen.

Für dieses Thema sind auch Delphi Windows Service und Tevent Delphi wichtig. Der Beitrag ordnet diese Aspekte verständlich ein und zeigt, worauf es im Alltag ankommt.

Projekt oder Modernisierungsvorhaben mit Net-Base besprechen.