1.\" $OpenBSD: sio_open.3,v 1.50 2020/06/20 09:26:54 schwarze Exp $ 2.\" 3.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: June 20 2020 $ 18.Dt SIO_OPEN 3 19.Os 20.Sh NAME 21.Nm sio_open , 22.Nm sio_close , 23.Nm sio_setpar , 24.Nm sio_getpar , 25.Nm sio_getcap , 26.Nm sio_start , 27.Nm sio_stop , 28.Nm sio_read , 29.Nm sio_write , 30.Nm sio_onmove , 31.Nm sio_nfds , 32.Nm sio_pollfd , 33.Nm sio_revents , 34.Nm sio_eof , 35.Nm sio_setvol , 36.Nm sio_onvol , 37.Nm sio_initpar 38.Nd sndio interface to audio devices 39.Sh SYNOPSIS 40.In sndio.h 41.Ft "struct sio_hdl *" 42.Fn sio_open "const char *name" "unsigned int mode" "int nbio_flag" 43.Ft "void" 44.Fn sio_close "struct sio_hdl *hdl" 45.Ft "int" 46.Fn sio_setpar "struct sio_hdl *hdl" "struct sio_par *par" 47.Ft "int" 48.Fn sio_getpar "struct sio_hdl *hdl" "struct sio_par *par" 49.Ft "int" 50.Fn sio_getcap "struct sio_hdl *hdl" "struct sio_cap *cap" 51.Ft "int" 52.Fn sio_start "struct sio_hdl *hdl" 53.Ft "int" 54.Fn sio_stop "struct sio_hdl *hdl" 55.Ft "size_t" 56.Fn sio_read "struct sio_hdl *hdl" "void *addr" "size_t nbytes" 57.Ft "size_t" 58.Fn sio_write "struct sio_hdl *hdl" "const void *addr" "size_t nbytes" 59.Ft "void" 60.Fo sio_onmove 61.Fa "struct sio_hdl *hdl" 62.Fa "void (*cb)(void *arg, int delta)" 63.Fa "void *arg" 64.Fc 65.Ft "int" 66.Fn sio_nfds "struct sio_hdl *hdl" 67.Ft "int" 68.Fn sio_pollfd "struct sio_hdl *hdl" "struct pollfd *pfd" "int events" 69.Ft "int" 70.Fn sio_revents "struct sio_hdl *hdl" "struct pollfd *pfd" 71.Ft "int" 72.Fn sio_eof "struct sio_hdl *hdl" 73.Ft "int" 74.Fn sio_setvol "struct sio_hdl *hdl" "unsigned int vol" 75.Ft "int" 76.Fo sio_onvol 77.Fa "struct sio_hdl *hdl" 78.Fa "void (*cb)(void *arg, unsigned int vol)" 79.Fa "void *arg" 80.Fc 81.Ft "void" 82.Fn sio_initpar "struct sio_par *par" 83.\"Fd #define SIO_BPS(bits) 84.\"Fd #define SIO_LE_NATIVE 85.Sh DESCRIPTION 86The 87.Nm sndio 88library allows user processes to access 89.Xr audio 4 90hardware and the 91.Xr sndiod 8 92audio server in a uniform way. 93.Ss Opening and closing an audio device 94First the application must call the 95.Fn sio_open 96function to obtain a handle to the device; 97later it will be passed as the 98.Fa hdl 99argument of most other functions. 100The 101.Fa name 102parameter gives the device string discussed in 103.Xr sndio 7 . 104In most cases it should be set to 105.Dv SIO_DEVANY 106to allow the user to select it using the 107.Ev AUDIODEVICE 108environment variable. 109.Pp 110The following values of the 111.Fa mode 112parameter are supported: 113.Bl -tag -width "SIO_PLAY | SIO_REC" 114.It Dv SIO_PLAY 115Play-only mode: data written will be played by the device. 116.It Dv SIO_REC 117Record-only mode: samples are recorded by the device and must be read. 118.It Dv SIO_PLAY | SIO_REC 119The device plays and records synchronously; this means that 120the n-th recorded sample was physically sampled exactly when 121the n-th played sample was actually played. 122.El 123.Pp 124If the 125.Fa nbio_flag 126argument is true (i.e. non-zero), then the 127.Fn sio_read 128and 129.Fn sio_write 130functions (see below) will be non-blocking. 131.Pp 132The 133.Fn sio_close 134function stops the device as if 135.Fn sio_stop 136is called and frees the handle. 137Thus, no samples submitted with 138.Fn sio_write 139are discarded. 140.Ss Negotiating audio parameters 141Audio samples are interleaved. 142A frame consists of one sample for each channel. 143For example, a 16-bit stereo encoding has two samples per frame 144and, two bytes per sample (thus 4 bytes per frame). 145.Pp 146The set of parameters of the device that can be controlled 147is given by the following structure: 148.Bd -literal 149struct sio_par { 150 unsigned int bits; /* bits per sample */ 151 unsigned int bps; /* bytes per sample */ 152 unsigned int sig; /* 1 = signed, 0 = unsigned int */ 153 unsigned int le; /* 1 = LE, 0 = BE byte order */ 154 unsigned int msb; /* 1 = MSB, 0 = LSB aligned */ 155 unsigned int rchan; /* number channels for recording */ 156 unsigned int pchan; /* number channels for playback */ 157 unsigned int rate; /* frames per second */ 158 unsigned int appbufsz; /* minimum buffer size without xruns */ 159 unsigned int bufsz; /* end-to-end buffer size (read-only) */ 160 unsigned int round; /* optimal buffer size divisor */ 161#define SIO_IGNORE 0 /* pause during xrun */ 162#define SIO_SYNC 1 /* resync after xrun */ 163#define SIO_ERROR 2 /* terminate on xrun */ 164 unsigned int xrun; /* what to do on overrun/underrun */ 165}; 166.Ed 167.Pp 168The parameters are as follows: 169.Bl -tag -width "appbufsz" 170.It Fa bits 171Number of bits per sample: must be between 1 and 32. 172.It Fa bps 173Bytes per samples; if specified, it must be large enough to hold all bits. 174By default it's set to the smallest power of two large enough to hold 175.Fa bits . 176.It Fa sig 177If set (i.e. non-zero) then the samples are signed, else unsigned. 178.It Fa le 179If set, then the byte order is little endian, else big endian; 180it's meaningful only if 181.Fa bps No > 1 . 182.It Fa msb 183If set, then the 184.Fa bits 185are aligned in the packet to the most significant bit 186(i.e. lower bits are padded), 187else to the least significant bit 188(i.e. higher bits are padded); 189it's meaningful only if 190.Fa bits No < Fa bps No * 8 . 191.It Fa rchan 192The number of recorded channels; meaningful only if 193.Dv SIO_REC 194mode was selected. 195.It Fa pchan 196The number of played channels; meaningful only if 197.Dv SIO_PLAY 198mode was selected. 199.It Fa rate 200The sampling frequency in Hz. 201.It Fa bufsz 202The maximum number of frames that may be buffered. 203This parameter takes into account any buffers, and 204can be used for latency calculations. 205It is read-only. 206.It Fa appbufsz 207Size of the buffer in frames the application must maintain non-empty 208(on the play end) or non-full (on the record end) by calling 209.Fn sio_write 210or 211.Fn sio_read 212fast enough to avoid overrun or underrun conditions. 213The audio subsystem may use additional buffering, thus this 214parameter cannot be used for latency calculations. 215.It Fa round 216Optimal number of frames that the application buffers 217should be a multiple of, to get best performance. 218Applications can use this parameter to round their block size. 219.It Fa xrun 220The action when the client doesn't accept 221recorded data or doesn't provide data to play fast enough; 222it can be set to one of the 223.Dv SIO_IGNORE , 224.Dv SIO_SYNC , 225or 226.Dv SIO_ERROR 227constants. 228.El 229.Pp 230The following approach is recommended to negotiate device parameters: 231.Bl -bullet 232.It 233Initialize a 234.Vt sio_par 235structure using 236.Fn sio_initpar 237and fill it with 238the desired parameters. 239Then call 240.Fn sio_setpar 241to request the device to use them. 242Parameters left unset in the 243.Vt sio_par 244structure will be set to device-specific defaults. 245.It 246Call 247.Fn sio_getpar 248to retrieve the actual parameters of the device 249and check that they are usable. 250If they are not, then fail or set up a conversion layer. 251Sometimes the rate set can be slightly different to what was requested. 252A difference of about 0.5% is not audible and should be ignored. 253.El 254.Pp 255Parameters cannot be changed after 256.Fn sio_start 257has been called, 258.Fn sio_stop 259must be called before parameters can be changed. 260.Pp 261If the device is exposed by the 262.Xr sndiod 8 263server, which is the default configuration, 264a transparent emulation layer will 265automatically be set up, and in this case any combination of 266rate, encoding and numbers of channels is supported. 267.Pp 268To ease filling the 269.Vt sio_par 270structure, the 271following macros can be used: 272.Bl -tag -width "SIO_BPS(bits)" 273.It Dv SIO_BPS Ns Pq Fa bits 274Return the smallest value for 275.Fa bps 276that is a power of two and that is large enough to 277hold 278.Fa bits . 279.It Dv SIO_LE_NATIVE 280Can be used to set the 281.Fa le 282parameter when native byte order is required. 283.El 284.Ss Getting device capabilities 285There's no way to get an exhaustive list of all parameter 286combinations the device supports. 287Applications that need to have a set of working 288parameter combinations in advance can use the 289.Fn sio_getcap 290function. 291However, for most new applications it's generally 292not recommended to use 293.Fn sio_getcap . 294Instead, follow the recommendations for negotiating 295device parameters (see above). 296.Pp 297The 298.Vt sio_cap 299structure contains the list of parameter configurations. 300Each configuration contains multiple parameter sets. 301The application must examine all configurations, and 302choose its parameter set from 303.Em one 304of the configurations. 305Parameters of different configurations 306.Em are not 307usable together. 308.Bd -literal 309struct sio_cap { 310 struct sio_enc { /* allowed encodings */ 311 unsigned int bits; 312 unsigned int bps; 313 unsigned int sig; 314 unsigned int le; 315 unsigned int msb; 316 } enc[SIO_NENC]; 317 unsigned int rchan[SIO_NCHAN]; /* allowed rchans */ 318 unsigned int pchan[SIO_NCHAN]; /* allowed pchans */ 319 unsigned int rate[SIO_NRATE]; /* allowed rates */ 320 unsigned int nconf; /* num. of confs[] */ 321 struct sio_conf { 322 unsigned int enc; /* bitmask of enc[] indexes */ 323 unsigned int rchan; /* bitmask of rchan[] indexes */ 324 unsigned int pchan; /* bitmask of pchan[] indexes */ 325 unsigned int rate; /* bitmask of rate[] indexes */ 326 } confs[SIO_NCONF]; 327}; 328.Ed 329.Pp 330The parameters are as follows: 331.Bl -tag -width "rchan[SIO_NCHAN]" 332.It Fa enc Ns Bq Dv SIO_NENC 333Array of supported encodings. 334The tuple of 335.Fa bits , 336.Fa bps , 337.Fa sig , 338.Fa le , 339and 340.Fa msb 341parameters are usable in the corresponding parameters 342of the 343.Vt sio_par 344structure. 345.It Fa rchan Ns Bq Dv SIO_NCHAN 346Array of supported channel numbers for recording usable 347in the 348.Vt sio_par 349structure. 350.It Fa pchan Ns Bq Dv SIO_NCHAN 351Array of supported channel numbers for playback usable 352in the 353.Vt sio_par 354structure. 355.It Fa rate Ns Bq Dv SIO_NRATE 356Array of supported sample rates usable 357in the 358.Vt sio_par 359structure. 360.It Fa nconf 361Number of different configurations available, i.e. number 362of filled elements of the 363.Fa confs Ns Bq 364array. 365.It Fa confs Ns Bq Dv SIO_NCONF 366Array of available configurations. 367Each configuration contains bitmasks indicating which 368elements of the above parameter arrays are valid for the 369given configuration. 370For instance, if the second bit of 371.Fa rate 372is set, in the 373.Vt sio_conf 374structure, then the second element of the 375.Fa rate Ns Bq Dv SIO_NRATE 376array of the 377.Vt sio_cap 378structure is valid for this configuration. 379As such, when reading the array elements in the 380.Vt sio_cap 381structure, the corresponding 382.Vt sio_conf 383bitmasks should always be used. 384.El 385.Ss Starting and stopping the device 386The 387.Fn sio_start 388function puts the device in a waiting state: 389the device will wait for playback data to be provided 390(using the 391.Fn sio_write 392function). 393Once enough data is queued to ensure that play buffers 394will not underrun, actual playback is started automatically. 395If record mode only is selected, then recording starts 396immediately. 397In full-duplex mode, playback and recording will start 398synchronously as soon as enough data to play is available. 399.Pp 400The 401.Fn sio_stop 402function puts the audio subsystem 403in the same state as before 404.Fn sio_start 405is called. 406It stops recording, drains the play buffer and then stops playback. 407If samples to play are queued but playback hasn't started yet 408then playback is forced immediately; playback will actually stop 409once the buffer is drained. 410In no case are samples in the play buffer discarded. 411.Ss Playing and recording 412When record mode is selected, the 413.Fn sio_read 414function must be called to retrieve recorded data; it must be called 415often enough to ensure that internal buffers will not overrun. 416It will store at most 417.Fa nbytes 418bytes at the 419.Fa addr 420location and return the number of bytes stored. 421Unless the 422.Fa nbio_flag 423flag is set, it will block until data becomes available and 424will return zero only on error. 425.Pp 426Similarly, when play mode is selected, the 427.Fn sio_write 428function must be called to provide data to play. 429Unless the 430.Fa nbio_flag 431is set, 432.Fn sio_write 433will block until the requested amount of data is written. 434.Ss Non-blocking mode operation 435If the 436.Fa nbio_flag 437is set on 438.Fn sio_open , 439then the 440.Fn sio_read 441and 442.Fn sio_write 443functions will never block; if no data is available, they will 444return zero immediately. 445.Pp 446The 447.Xr poll 2 448system call can be used to check if data can be 449read from or written to the device. 450The 451.Fn sio_pollfd 452function fills the array 453.Fa pfd 454of 455.Vt pollfd 456structures, used by 457.Xr poll 2 , 458with 459.Fa events ; 460the latter is a bit-mask of 461.Dv POLLIN 462and 463.Dv POLLOUT 464constants; refer to 465.Xr poll 2 466for more details. 467The 468.Fn sio_revents 469function returns the bit-mask set by 470.Xr poll 2 471in the 472.Fa pfd 473array of 474.Vt pollfd 475structures. 476If 477.Dv POLLIN 478is set, recorded samples are available in the device buffer 479and can be read with 480.Fn sio_read . 481If 482.Dv POLLOUT 483is set, space is available in the device buffer and new samples 484to play can be submitted with 485.Fn sio_write . 486.Dv POLLHUP 487may be set if an error occurs, even if 488it is not selected with 489.Fn sio_pollfd . 490.Pp 491The size of the 492.Fa pfd 493array, which the caller must pre-allocate, is provided by the 494.Fn sio_nfds 495function. 496.Ss Synchronizing non-audio events to the audio stream in real-time 497In order to perform actions at precise positions of the audio stream, 498such as displaying video in sync with the audio stream, 499the application must be notified in real-time of the exact 500position in the stream the hardware is processing. 501.Pp 502The 503.Fn sio_onmove 504function can be used to register the 505.Fn cb 506callback function called at regular time intervals. 507The 508.Fa delta 509argument contains the number of frames the hardware played and/or recorded 510since the last call of 511.Fn cb . 512It is called by 513.Fn sio_read , 514.Fn sio_write , 515and 516.Fn sio_revents . 517When the first sample is played and/or recorded, right after the device starts, 518the callback is invoked with a zero 519.Fa delta 520argument. 521The value of the 522.Fa arg 523pointer is passed to the callback and can contain anything. 524.Pp 525If desired, the application can maintain the current position by 526starting from zero (when 527.Fn sio_start 528is called) and adding to the current position 529.Fa delta 530every time 531.Fn cb 532is called. 533.Ss Measuring the latency and buffers usage 534The playback latency is the delay it will take for the 535frame just written to become audible, expressed in number of frames. 536The exact playback 537latency can be obtained by subtracting the current position 538from the number of frames written. 539Once playback is actually started (first sample audible) 540the latency will never exceed the 541.Fa bufsz 542parameter (see the sections above). 543There's a phase during which 544.Fn sio_write 545only queues data; 546once there's enough data, actual playback starts. 547During this phase talking about latency is meaningless. 548.Pp 549In any cases, at most 550.Fa bufsz 551frames are buffered. 552This value takes into account all buffers. 553The number of frames stored is equal to the number of frames 554written minus the current position. 555.Pp 556The recording latency is obtained similarly, by subtracting 557the number of frames read from the current position. 558.Pp 559Note that 560.Fn sio_write 561might block even if there is buffer space left; 562using the buffer usage to guess if 563.Fn sio_write 564would block is false and leads to unreliable programs \(en consider using 565.Xr poll 2 566for this. 567.Ss Handling buffer overruns and underruns 568When the application cannot accept recorded data fast enough, 569the record buffer (of size 570.Fa appbufsz ) 571might overrun; in this case recorded data is lost. 572Similarly if the application cannot provide data to play 573fast enough, the play buffer underruns and silence is played 574instead. 575Depending on the 576.Fa xrun 577parameter of the 578.Vt sio_par 579structure, the audio subsystem will behave as follows: 580.Bl -tag -width "SIO_IGNORE" 581.It Dv SIO_IGNORE 582The devices pauses during overruns and underruns, 583thus the current position (obtained through 584.Fn sio_onmove ) 585stops being incremented. 586Once the overrun and/or underrun condition is gone, the device resumes; 587play and record are always kept in sync. 588With this mode, the application cannot notice 589underruns and/or overruns and shouldn't care about them. 590.Pp 591This mode is the default. 592It's suitable for applications, 593like audio players and telephony, where time 594is not important and overruns or underruns are not short. 595.It Dv SIO_SYNC 596If the play buffer underruns, then silence is played, 597but in order to reach the right position in time, 598the same amount of written samples will be 599discarded once the application is unblocked. 600Similarly, if the record buffer overruns, then 601samples are discarded, but the same amount of silence will be 602returned later. 603The current position (obtained through 604.Fn sio_onmove ) 605is still incremented. 606When the play buffer underruns the play latency might become negative; 607when the record buffer overruns, the record latency might become 608larger than 609.Fa bufsz . 610.Pp 611This mode is suitable for applications, like music production, 612where time is important and where underruns or overruns are 613short and rare. 614.It Dv SIO_ERROR 615With this mode, on the first play buffer underrun or 616record buffer overrun, playback and/or recording is terminated and 617no other function than 618.Fn sio_close 619will succeed. 620.Pp 621This mode is mostly useful for testing. 622.El 623.Ss Controlling the volume 624The 625.Fn sio_setvol 626function can be used to set playback attenuation. 627The 628.Fa vol 629parameter takes a value between 0 (maximum attenuation) 630and 631.Dv SIO_MAXVOL 632(no attenuation). 633It specifies the weight the audio subsystem will 634give to this stream. 635It is not meant to control hardware parameters like 636speaker gain; the 637.Xr mixerctl 8 638interface should be used for that purpose instead. 639.Pp 640An application can use the 641.Fn sio_onvol 642function to register a callback function that 643will be called each time the volume is changed, 644including when 645.Fn sio_setvol 646is used. 647The callback is always invoked when 648.Fn sio_onvol 649is called in order to provide the initial volume. 650An application can safely assume that once 651.Fn sio_onvol 652has returned a non-zero value, 653the callback has been invoked and thus 654the current volume is available. 655If there's no volume setting available, 656.Fn sio_onvol 657returns 0 and the callback is never invoked and calls to 658.Fn sio_setvol 659are ignored. 660.Pp 661The 662.Fn sio_onvol 663function can be called with a 664.Dv NULL 665argument to check whether a volume knob is available. 666.Ss Error handling 667Errors related to the audio subsystem 668(like hardware errors, dropped connections) and 669programming errors (e.g. call to 670.Fn sio_read 671on a play-only stream) are considered fatal. 672Once an error occurs, all functions taking a 673.Fa sio_hdl 674argument, except 675.Fn sio_close 676and 677.Fn sio_eof , 678stop working (i.e. always return 0). 679The 680.Fn sio_eof 681function can be used at any stage. 682.Ss Use with Xr pledge 2 683If the 684.Nm sndio 685library is used in combination with 686.Xr pledge 2 , 687then the 688.Fn sio_open 689function needs the 690.Cm stdio , 691.Cm rpath , 692.Cm wpath , 693.Cm cpath , 694.Cm inet , 695.Cm unix , 696.Cm dns , 697and 698.Cm audio 699.Xr pledge 2 700promises. 701.Bl -bullet 702.It 703.Cm rpath , 704.Cm wpath , 705and 706.Cm cpath 707are needed to read, write or create the authentication cookie 708.Pa ~/.sndio/cookie . 709.It 710.Cm rpath , 711.Cm wpath , 712and 713.Cm audio 714are needed when the device is a local raw device. 715.It 716.Cm unix 717is needed when the device is a local 718.Xr sndiod 8 719sub-device. 720.It 721.Cm inet 722and 723.Cm dns 724are needed when the device is a remote 725.Xr sndiod 8 726sub-device. 727.El 728.Pp 729Once no further calls to 730.Fn sio_open 731will be made, all these 732.Xr pledge 2 733promises may be dropped, except for the 734.Cm audio 735promise. 736.Sh RETURN VALUES 737The 738.Fn sio_open 739function returns the newly created handle on success or 740.Dv NULL 741on failure. 742.Pp 743The 744.Fn sio_setpar , 745.Fn sio_getpar , 746.Fn sio_getcap , 747.Fn sio_start , 748.Fn sio_stop , 749and 750.Fn sio_setvol 751functions return 1 on success and 0 on failure. 752.Pp 753The 754.Fn sio_pollfd 755function returns the number of 756.Vt pollfd 757structures filled. 758The 759.Fn sio_nfds 760function returns the number of 761.Vt pollfd 762structures the caller must preallocate in order to be sure 763that 764.Fn sio_pollfd 765will never overrun. 766.Pp 767The 768.Fn sio_read 769and 770.Fn sio_write 771functions return the number of bytes transferred. 772.Pp 773The 774.Fn sio_eof 775function returns 0 if there's no pending error, and a non-zero 776value if there's an error. 777.Sh ENVIRONMENT 778.Bl -tag -width "SNDIO_DEBUGXXX" -compact 779.It Ev AUDIODEVICE 780Device to use if 781.Fn sio_open 782is called with 783.Dv SIO_DEVANY 784as the 785.Fa name 786argument. 787.It Ev SNDIO_DEBUG 788The debug level: 789may be a value between 0 and 2. 790.El 791.Sh SEE ALSO 792.Xr pledge 2 , 793.Xr audio 4 , 794.Xr sndio 7 , 795.Xr sndiod 8 , 796.Xr audio 9 797.Sh BUGS 798The 799.Xr audio 4 800driver doesn't drain playback buffers, thus if sndio 801is used to directly access an 802.Xr audio 4 803device, 804the 805.Fn sio_stop 806function will stop playback immediately. 807.Pp 808If the application doesn't consume recorded data fast enough then 809.Dq "control messages" 810from the 811.Xr sndiod 8 812server are delayed and consequently 813.Fn sio_onmove 814callback or volume changes may be delayed. 815.Pp 816The 817.Fn sio_open , 818.Fn sio_setpar , 819.Fn sio_getpar , 820.Fn sio_getcap , 821.Fn sio_start , 822and 823.Fn sio_stop 824functions may block for a very short period of time, thus they should 825be avoided in code sections where blocking is not desirable. 826