Skip to content

Monitor

Jump to bottom
David Dight edited this page May 26, 2023 · 29 revisions

1. Introduction

The fiber_monitor class encapsulates a configurable monitor window displayed in the current terminal. By default, the window is the entire screen. The data displayed reflects the current state of various aspects of all running fibers in the current thread. Each thread has its own unique fiber manager.

Your application can simply create a fiber_monitor object, and call it periodically to display the updated monitor in real-time.

Note that the data exposed through fibers::const_get_vars() is not threadsafe. If you wish to concurrently monitor fibers from multiple threads you will need to manage the concurrency for these objects.

montest2 - example monitor application
Screenshot from montest2 with 20 fibers working in one thread and using fiber_monitor

1.1 Columns

The fiber monitor displays the following columns:

Name Description
# The position of the fiber in the scheduler queue. 0 is the current (active) fiber, also marked with an *
fid The unique fiber_id of the fiber. NaF for main (Not a Fiber)
pfid The unique parent fiber_id of the fiber. NaF for main
prev The previous running fiber_id
ctxsw The number of context switches this fiber has been scheduled to execute
t(ms) Total time in ms this fiber has been active (switched to)
^t Time in ms this fiber has been active since it was last active (switched to)
stack ptr The address of the current stack pointer (esp)
stack alloc The address of the allocated stack (0 for main)
depth The depth in bytes of this fiber's stack (stack used)
stacksz The total size in bytes of the initial available stack
flags A representation of the internal fiber flags (see below)
ord The launch_order of this fiber; defaults to 99
name The optional name of the fiber

2. API

ctor

fiber_monitor(std::chrono::milliseconds timeout=std::chrono::milliseconds(1), sort_mode mode=sort_mode::by_id);

Create a fiber_monitor that will display in the current terminal. Parameters:

Parameter Type Description
timeout std::chrono::milliseconds timeout (update interval) value in milliseconds
mode sort_mode default sort on specified column (by_sched, by_id, by_ms, by_tms, by_name, by_flag, by_ctxsw)

Nothing else will happen after construction. You must call update for anything to be actually drawn to the screen.

update_row

void update_row(int row, int pos, bool iscurrent, const fiber_base& what) const;

Update the terminal monitor screen with the latest fiber info for a single fiber record. Parameters:

Parameter Type Description
row int y position (screen co-ordinate)
pos int record number (0 based)
iscurrent bool if true this is the current fiber
what const fiber_base& fiber_base record to use for update

update

void update(window_frame winpos=window_frame(), const fiber::cvars *vs=nullptr);

Update the terminal monitor screen with the latest fiber info for all fibers. Parameters:

Parameter Type Description
winpos window_frame top left xy, lower right xy window position (screen co-ordinates), default is the entire screen
vs const fiber::cvars * pointer to cvars record to use; if nullptr use default

is_quit

bool is_quit();

Return true if the user has pressed q to quit the monitor.

operator!

bool operator!();

Return false if the user has pressed q to quit the monitor.

get_dimensions

xy_coord get_dimensions();

Return a xy coordinates of the current screen. xy_coord is a std::pair<int, int>.

get_terminal_dimensions

static xy_coord get_terminal_dimensions();

Return a xy coordinates of the current screen. This can be called before creating a fiber_monitor to get the window size. xy_coord is a std::pair<int, int>.

user_key_process

virtual bool user_key_process(char key);

User overridable keyboard processing. Implement to add additional key commands. Return true to quit.

3. Usage

Setting up your monitor

To use the monitor, instantiate a fiber_monitor object (see parameters above). The default arguments are usually sufficient for most use cases. After construction, nothing is displayed yet. You can call get_dimensions() to obtain the xy dimensions of the default display window. When you wish to update the screen, call update(). With no arguments, update will display using the entire screen. If you wish to update only part of the screen, you can specify the upper left xy and lower right xy by passing a window_frame object. The reason this is made available is if you have multiple threads updating the monitor, you can partition the physical update to the window given. Note that the monitor is not thread safe. You will need to manage any potential data race by either using some form of concurrency primitive or copy the fiber::cvars object within the thread, and pass the copy to the update.

User input

Within the call to update(), the user can enter a few keyboard commands:

Key Description
1 Sort by scheduled order
2 Sort by fiber_id
3 Sort by time used (ms)
4 Sort by delta time used (ms)
5 Sort by fiber name
6 Sort by fiber flags
7 Sort by number of context switches
8 Sort by stack depth used
9 Sort by fiber launch order
SPACE Selected next sort type
p Toggle pause updating
x Exit the monitor

4. Examples

1. Simple monitor of multiple fibers - montest1

This example demonstrates the following:

  1. Integrating fiber_monitor into an application
  2. Passing fiber_monitor options, configuring the monitor
  3. Constructing fibers using make_fiber and fiber_ptr
  4. Observing stack usage
  5. Using keyboard commands, exiting the monitor, detecting an exit
  6. Using global_fiber_flags::skipmain
  7. Using fibers::kill_all() and fibers::resume_main()

Using the static method fiber::monitor::get_terminal_dimensions(), the dimensions of the current terminal are obtained and the number of fibers to create is determined. The fibers are created with a variable stack size and additional parameter which controls the number of iterations to be performed. The fiber is also named using set_params.

By default, the application sets global_fiber_flags::skipmain which prevents control returning to main while other fibers are active. The effect of this can be viewed in the monitor by observing that the number of context switches for main stays constant at 1.

If the retain switch is passed, the application sets global_fiber_flags::retain which prevents the fiber manager from removing fibers when they have finished. The effect of this can be viewed in the monitor by observing that the number of fibers with the 'f' flag growing.

The main function then goes into a loop while has_fibers() is true. If the fiber_monitor object fails a boolean test, this indicates the user has pressed exit. In this case fibers::kill_all() is called to remove all active fibers before exiting the loop.

In the function foo::func the fiber loops and yields. In each loop, the fiber consumes a variable amount of stack. This usage is visible under the depth column on the monitor. If the user presses exit, the fiber_monitor object fails a boolean test, and the function jumps straight to main (via fibers::resume_main()).

./montest1 --mode 8 --retain --interval 0 --sleep 25
montest1 - example monitor application
Screenshot from montest1 showing fibers working in one thread and using fiber_monitor

2. Example doing some real work - montest2

This example creates 20 fibers by default. Each fiber is given the task of generating the power of 2 from 1 to 2999999999 or (maxexp) exponent ($2^{1-2999999999}$), randomly chosen, between 10 and 30 times, using GNU gmp. Each calculation can take from 1 to 1000ms to complete. After the value has been calculated, it is added to a total and then the fiber yields. Each fiber continues to calculate the values until it has completed the number it was given to do. The fiber does not perform any sleeps.

Before it begins each calculation, the fiber changes its name to a string showing the value it is going to calculate (possibly truncated), for example 2^8766964 (depicting $2^{8766964}$). When the task is completed, the fiber changes its name to finished.

Passing the --percent flag will show the amount completed instead of the value being calculated.

The calculated values are not displayed, however they can be saved to disk by passing the --write flag to the program. Each fiber will write all of the results to its own output file including the sum of all the values calculated. It will be seen that a lot of work has been performed by each fiber (see below).

You can adjust the value of maxexp to set an upper limit on the size of the exponent to suit the capabilities of your environment.

If the user presses q, fiber_monitor will set the quit flag to true. The fiber will immediately switch back to main. Main detects the quit flag and stops any further processing by killing all the remaining fibers, then exits.

montest2 - example monitor application
Screenshot from montest2 showing fibers working in one thread and using fiber_monitor
output 

$ ./montest2 --write
$ cat worker0.out | more
2^8766964 = 136428869127054913853253313098808388476612529464126449296924120793256821549730388375844099113201856474302
705864683363028957166390222337390911847421381280738166241847875914022340797390301850801322539114163913806557018288014
475501997603173039037822685309234407825512754239284141735768421678632002836687501933031398633563645196765166401693515
647777563591158439748443589427854281889064450437282239309057141350148738904810118620115500830996046752165667668396478
763339562306340919640196257708595121872379207506024272949422747958324254273005548852219733685827487317971217007219260
122740126659149754546776191052415548256600253596475226663434108443022428960566788870639904179430213466020687837472342
460478419859825830833484828822052060619292919219258586022842059352880614578488421863664336145992717824263683937604400
459111005803422785386855879827097939962489097875294056311857099962552897411422067992651394419546658599784756638661368
664623099789079454371236465409709945804366991293298678818507257831147177842470545138765249076679097890184426425408162
005858367362155234076838724971802754198466483823407147709631089137162783798293345097755712784781451125462692700981185
652621874609626689023191229159439537678483627676233450657368597656587154320487649171728921493682712054362241590051086
627873503169974052585485402428374592800689330166177044688281698455038628842292382242181311737614595686866043189635136
947263437149612816270125321934577794290214568089152190256519989935954936718053346606005926557328005491757895804864469
425820333629645586308040346156974097811996835599852217785238177058231921261786361492244534728128557071121721055777539
464613033533701515341529817459877171816965362008323985663879677000923451375608199410609572980492361302956101539967259
089049496980488447806573405907148347669679244220974975440811204681890365305641985539376108653510823890637110950649385
612320780134146388424690925121851000968356272640777585019589317924425712569647733587379324648696017051979418698792371
298547695821771491182989592420511521958280984887305030513662321895541931381113779711368648304289650733451211156555205
932342831303613460498784520469798051524290445392076333436072603795727197735796201453685796635343307744402396072279280
447317375449599214326183828270171438165516936818745741044158482007976755755863719976176406515363770592845488435301681
502226629339199944415549700911003969635490830609859356007603069934949183193042352683240351059501163247911595006567651
681737553769090319148842517483939264430165172776059248253561711369445025673538406404005683736646380811187669341120712
359883221915381171363671057040010134870508902723870185685657180242998703664989716475870244657505300379044787282831260
270684900462666786528093731339228952844339272454013911223589014699618667722866127255967756528056698795254297606280363
020739080916092296092898175305865713886916953530418104538443935625667905276968664761486146695203360230062336373000611
357281437345505784944363825049868790817035969611930821482554238043667220697708224659838957362485037669658023368728020
111669400894606903250195508440463734068460055208531973606103943466971721143844904490418287722267346049468332867221141
575034838176608139091218732982842845362424928239890965574830370644366971174182878859422360230765616824343073874453767
657379508390470840910876893036035549366049796594828990043615168434980238136954754783338755627383684481095303323663445
895424477487019787760575612905505927914131116314946379577671639942830399810273923486954145683016830045122051814192665
819800604363319682348769514046407002632382689086112655808357135892031282510666648003215754539273523381955432439659369
517976074948932867439365209003747988667830038002883861521094495465827031631890188703639276153301931802356762627346243
879033629756210010403503589819520479223212532576377940511997571397639259557305752422455836165582695755709004694171682
050430842092058547122179066700906067626930110728561312843391062423420039893445112558940106001840656327274357490357985
360578515847065597722069601717632348621254022223241761454277086523066710849399045826115514999274627729159284687924538
007483148458755346093215405228768851364481394575635408845004828497655735960984180796005676531124694418911687796873187
625297966211812039153877881167058582912844629585729172445743780488604286958025056173335747087919849614192481080707397
346218480897638362000159616126229266957415006017410527568342236337200826637393588954434203199786657429704945587889665
196983163873732922822880660266095219017019936680902443160882328292691621362511626149097050687701731450888588070115248
890546518415589040683390895503458681047883266962735048646340297081354850920982660502030775546349698953605502320929790
513044320860561204347732166058413633662584232501938845020943714719396593911718404494391633576869206191115498526002229
004099135309573699860923413787468475492783877046392671510771436373362144336031008386707713298545065498720973278684618
061070153389828405439932171345612776237716013093530027564442398979656243064971564560446118926030374624152393942402025
215903474963812624190765224394356132429548292306542105885255060833841489143391432999640405836667566391156556554162154
387158927572973288519653235622376540272595422834590971287556732575120916780145370412726503921262004570823595382528175
098146732404726821239378224715034682204138076059067740896123724615220390589092283279194159053594985510140126689359442
998542973920856519535383922426837039060527584117596445694497971656373532323329355196903898345110129442023049914153504
481935515695859418473565004647126641015996907832650156114298027800331896680440381118238894056099200923030585231274080
580247197425187998973193165042818505881188011548484664982407151033984601292759965888698566300567285646067591967456389
436751095334564239578310632624969955261168290367768368400266357272117102519809611261770989387906973057926991513103543
767132460725335956658969822211331523553879939806384662181823559227975010709076819901037186196358096475785098521083931
519424780096353781943723287606937158513964759371083851517880961289751473368461159017332186246955010219816639915856230
574888636162982979232717511315251647472687665496371796924021182951179833078886465963715312030499172543443537029677220
750118369953771064889780443669068332896970961075836197582565768463297370094275557790794808518925704136802534330877562
405571904784460824447362269243503945792235717129267970083856146774544523564995282613404301293102129169281002969725792
440523237076340480640069193629854360677929274191775054700752860780911541571479511698751162124187782180152663384826617
390685272858559466292904435497440341919156486687124505838057450618449562550022905096390429835651054479106234866429578
866184425556065691378026120312251266919660189716268097351930389444752715357336838109068507580663582579876540127389641
073138467098999036108659407446854428158272520286920004508408603081364855017158026591944134529347163699408805707380796
300426437599429321709519691981782113181533014098620961178682972751960616061014797022705693507636880724347514384365415
982654500942823596910483924296226540479148914178556322388588158981885444865847276792769223746202086539551785474803151
017793096086399999896206036347914119105295165593590606073443588879301764586164267991045517843256516335660237147130545
685242468689491512255622612488586452034670188977082440635260063322500608344955463775194216184444069381163716585911741
290274598071756478987223223548596178368925343830395876105831810500737858315282144388474240875956896443067574580738460
321938678710339084825396615068641057001298429517212010252073370224130497766267544975101881989136966251656156321053221
401099222923303583417624545606109467799830530138624117081306906201106032794872815171109205634165014245684613703417578
882778352704381251102699013107333253194782619236748790847318271147079765577977321170221876460297522052596189653682678
440010440506950464201577228090914886008705901235791541318674818205690513636175942189863419922569280893949590367288786
643554767599970096809216160774768804265213712815270333093865699895881211022473019816664269400198774943881560467445363
415653476513270471342539525237680581131011422387261426992115494976944107324212944345397798524660724625985963154047296
674995622615442705456557052025080917806873992304495011178854977850422059581320399609796015494194062138956510175730332
280069489322544437572582687271298471364577168447194695588323922724859013983629182897582099568743562754049410183409399
397461943945917870584983490471605035949348872951654164043726853758373745362169546938907865358953854424790705638396810
805983764386485906052367053399985705926628880094011067991740700975710710898784808618403247327777789744997347996958448
370520059495228190211651310793646971344336479915574023203006043631092716146951044205434601261563492586036687362719111
209815305651870326197759277937804643931938736845327029429315286259754233461012924607913289262166419048875305422119005
987124487529001027733460953178242181989953988871780069910268038664442960096735885959894895902023343668649366586006222
751874950254294082729941224802465267313223589457638744393946192324073957067746423407353873496682551238452925583744713
445342794333754089437933829937597458051002137042136175162899288616086520127340997834992112594022024857084478956124376
902371588228136670671736570142889561195706185040463033222588695046859183850353744074748595863906397969088929526605824
972403517498243248262016714235379156539422266564077921936649729568263021163298720160497712455956024711844813378913061
301921144926365520963683573218932581352941567732369340525839346759232596580766349693352569719281281526763693713439711
952592858189388859036247764643723728804869259895234743588750030734750586369595770177848148048654184136677716178532277
410081536708065317391422153364546928229120642868649756617662900076815602425424100970556047080279919548816253375599955
099277446020900254299551090668296981804719957443375837525946924164229825248528995543212563611415539711604137144954525
886558541142977157210725455027792646986349085461831428898756793889903760826172239471971952528774636007008951647456345
345856956113803322771054118967144843350464116598530313656361729347294202041235025654130987008596119735761580677055404
400941149941122209609372455952492781961297564598839427559851495275515283420348586954153095169233482505939237418881471
127717230709598101241043383573107097863231913913548180600317985491672076626010522359842686064154122304209399469130523
356853188444276757493452979938569753881361577744724461190858842010800326902876919403271384044350055209585033923338146
150676776635721369290552550104502683395003028087455300110117364469272282138426545040813608096847839446482982805843353
231722390871757607012612359698977229088860267070053298950808352376415286573382499995554347875297329997985588046867485
382364947802695484834749803608146907833346698575647411416531528776022768670614925745140650091998574439364943902562921
781001116657453099945955820713638784253077864531286881865458161034675691713806354963822007575150760505861967982632095
657673810893506099721408842751426645456104582409536926781585898276114370680270536963690434763343433541340539343722660
093429904168596586061631108911793662040161941229090335016536479150468850175895539929542076133175888586592543174963587
539163405149641078630066712474820265922461351524604046247074962893317361948693703939374944813288802350923490584334940
790940084092788562376416709373357999604578974398715997730807701156589689740130416302643072824783817580103049130330744
303422005411024093628164538792805132270457088178062752342666461628540501479571419988523540105489986650624846645559949
482893472701449882013657886720263434683756269716823883345128989810605809469089518050228406511527258939180301510270035
634370538492233403377416440228855338176265875081282513527329866793873532655295492476633714722066185477126821769987553
618806021593767014566071321696849048421156330052317453604616303783178431155561412042798841508253151840034061089463740
172467591044643719463246648908493602507748276166642804105691562801627576669592180018650679463965030913131356541486616
725011632028320000422110495388693922518812409788200275746005670512292948161731344781091280156767845340608440877830185
321100216487307484741949089797230309065675099792365014095635464561507084587768513554064360649544003663466678185681991
858586597073215295298068597895524619558171071417771652876425368063244672534497712463498281904087550737528695097871830
630072185134677446969874694820384405030756005324298960817938650715644168270710059980667526887972648142292787009018461
298114017277548715495095228650257413422630554258109478569066839012472311251183769961184576110509217267605417426297473
102319030924149789664910760599301045548821815707979298815416070261359916063966315260255039648740168747887172943399387
894130091659455841192172110591043504911318269779862026735467740880309594932783713552342560363780799523723770488789924
200665760695686504750962758336618306230839692874088641825341510781315510960860802111551966714972790558077932784446368
238725450794176775827983552834682978259831628498234067787563374801694198493842815157594450302715128835075816298024877
660684861069624022793592060024356848993065572682158653493563187531605397357947068426783247920413173604753327302150722
738379664484179150998095257176466087742437228897487591049600485754232538612246189181114763071311571427163913731490307
597033107735545595406732114220625369643100509586599416252090543200349974023192670532322600355980161954452536409412612
079492301669986107758726019823193888027846173341382068626320893502952968424008043290437515469761928350710294915134232
544036122299158853083132998577678053229628962755408746380988147228633809424543577186886798072415414487516332804594555
345245208533715824091983763743787341635460458166753616304900764196369717202430105500428047702592661333345309791817600
764375865577961577423179242284783838911090593777640983726591710593117072586110564241227741836167597320925603772666269
627089620530234673406832260895656167105129979617975445135733698041233566789337804439796883202789012539214169633005445
979877503994622001607597431149143158345009863269700308462212024518888888716216458055261774773700753238744107726202335
234447706549250314683974943647110182988921142618415060095732157471148519959420346777900575228299492891565534733565044
850910582477174102528471657417459927444121585175006549840779776399451987775923134817088405605592422796472203403003959
434544896030506911729622892230934820280994266248745830739135104873903180432867470078234018890532115403784193684603197
077463870123082790126247359248424040097952610384181767367027884484101970750351919288340681966433066197174442735540523
982324305385987490717266445288201934471688026396528577922337466455405454702719122179066551688637585935614021841093516
452199957061731552612981089314125709286806809795166776035421066129341258092686688629234066327710992079182935933688351
748805138227406695749177405860626590964212319297406209699320739788187013775473595672460080103235020797908611546821780
433668608760316797860139079978026599258512002709632746926979919026901619635345190658712466412731328969393126354617403
615922423229885851968757343969649474275854594216496270227606739490767410521078370979245740501633629852101469264781406
442225342197480944651751124583544352171893785599188921296403278806869977885192517429767897118437090177858400737683978
075010512782374981772674789790706763114216900909121122484849331758371685755850002751971058705228641454855480631028817
825029321575189406558983252454497661972543733489192804007505815077339228215729933778859302155588339246101990698202890
612779438972061330358583165350523962293903185779283238339782954962185088819765536573699445639788050464844156301506343
696869208234009074125467739623547687566003876664582382418946396179875607656943257304353837831816567891713983446551883
980069338806914564182943877421504709143317238781398945277680600969435155600824758970105100102929435750681585824659948
865139176261309525729445512462988199378439213452949377233327485859204785401836090226580275958333535263520978240490265
916836206647085588311084148388949854558964987022810065374132792898507820801937499426925435959215534965391373695101933
210569705624812067066542139668315895786021346431429753898331604566192036518343251357166404329601525014869865987928339
059826234301679746240669149303003792143777888879468385870409117323461123850856152530632005397895714024718980231622193
413990602162099103829295479780671254771205827135288247144701122182672443930059864705230614072997588999034727362566409
424700552125775710547124782831008257376102853783543479520612082638488827722134295492864467100486151533886760892186867
585319864412967702119303727487362798585683334314298299429657836677844237402073638902387447850061510968054938821943320
080602670686818553644188940852586305172504039024663446371326581232424696600527258563087949849966466356699727347246673
590018916751965641488740711121641843432232887656420880374938096101821247464633889797383667820228708993515301352715935
585132420847284636619854130060553372952180099302698188225565464392189911624836885793436912373640767896933681362089098
824603875645037335480550907874262444452966527961734716798130808275823792453110397276670233019057445136813034687883541
297612708889246225355047891135530637571731822739575269844434111915141068324238075459169591323793322548655683243492598
562214817592815579634433595485904614669810271167962898149812915078861471851298822670872604837958936883956216210404437
637069680441033747115985392376157171784216916703844952651595054509592758184520189741181428674364205404694099911869506
205018374129283190777799856635331803961062678218467128528406231457313529324925512656645504645721932778907204590256322
126716788231171605976588657374028963286239784261495063886690457789712179142517021276996549233417513534078137890346710
760771353563506412953461804140740261793505917364538137328598059565827762180088556369690918913374749026764069865548730
680212647384676144888919828387713451508531435470207200650981871652089820532640518397512129394050181000266620473546992
875098140049177136657903423680596963375617743649033026456926328577010654707916612730448817781543808848586763544132624
920324910850226419455343196681904900923562108728837651399502278513126498595127802288873366493200123121331034133203092
922968652829348791293789079767597345655965667731207737617505502489437139340359944881282661757696120824880826327550107
829800914242076956224126871060691835037524416718349243161115404056012584415707408225538788672751040909552952320183111
780165732503943277559273942691667518277410042522867277904403236238992934991953962725179840084897487981542084318945897
819890740441248610411216026472774542870954369058014242171154475175445994779022368848738705052373874201645974268719074
829550176091228345965576355071569492783705676192846797365115631193518878279665411569106834039365634115694523721707353
445307180029887776520304610911539094630678842065204850456439850648126457176638331502910511456712683283020667577017648
928095719894428700216847960543552498180717732490923789239888995190681435856520700481431187510593084516289658133822706
450975933867566116700506939141108457844205867936437788263075370837883793341112251364709513911855260363100250004592252
163115362041968546224688357533879366514364007346291948050168655330697192623631277132270627528963109243821245515520931
511651500842251062668785038745176802559227213840090537818415547574618057952052348961634783902205516736982211192462450
953375395010129600727192777060842343338620384807477633676979531840250839693236629793753879379717051762368941253280099
026230434405756759147990874655164984674890455234773412913338928243774167916372108116518948910628511951158427935835859
769061672586988886325001195914590660556353646854559257956258682649950230381505698887931749023364941950716693036963798
658743633982936507373715362675293282601262908790163123460605946229015545408241599906404408354923244524342316289773497
--More--
Clone this wiki locally