Limiting the number of items read

You can limit the total number of items read from any folder or the entire mediastore. An excessively large number of items can make using the device very slow and can cause poor response times for synchronization operations such as changing priority folders or determining mediastore changes.

<MaxFolderItems>

The <MaxFolderItems> element controls the maximum number of items read from a folder. The configuration file can contain only one <MaxFolderItems> tag; its value will apply to every folder on every mediastore. Currently, only the block filesystem (BFS) mediastore synchronizer (bfsrecurse) uses the value in the <MaxFolderItems> element; other synchronizers ignore it. The default setting for <MaxFolderItems> is 0, meaning there's no default limit on the number of items read from a folder.

To keep the count consistent, independently of the type of items in the folder and of their contents, mm-sync calculates the number of items in a folder before performing any filtering based on the <SyncFileMask> setting. Because “.” and “..” are always ignored, mm-sync compensates for these files when it calculates the number of items in a folder. When a synchronization reaches the limit set by <MaxFolderItems>, mm-sync stops synchronizing the folder and delivers the MMSYNC_SYNC_ERROR_FOLDER_LIMIT event.

When you configure a limit on the number of items read from any one folder by setting <MaxFolderItems> to a nonzero value, the filesystem readdir() operation determines which folder items mm-sync sees. The mm-sync service doesn't see items beyond the <MaxFolderItems> limit and doesn't consider them when checking for folder changes. These unseen items may include media files, playlist files, other folders, and files that have been filtered out or that, by definition, mm-sync doesn't handle (such as .xls files). Adding or deleting items from a folder on a mediastore affects the presentation of the items to mm-sync (depending on the operation of the readdir() function) and may cause unexpected changes to the database for the mediastore.

<MaxMediaStoreItemsConfiguration>

The <MaxMediaStoreItemsConfiguration> element and its contained <MaxMediaStoreItems> elements control the maximum number of items read from mediastores. There can be only one <MaxMediaStoreItemsConfiguration> element, but it can have multiple <MaxMediaStoreItems> elements to set distinct limits on the number of items read for different mediastores. Each <MaxMediaStoreItems> element must have a mediastore attribute set to the mediastore path and the element value set to the limit on the number items to read. You can use wildcards in the mediastore path. For example, the configuration element <MaxMediaStoreItems mediastore="/fs/usb*">100</MaxMediaStoreItems> means the devices located at /fs/usb0 and /fs/usb1 both have a maximum of 100 items read.

Currently, only the following mediastore synchronizers use the values in the <MaxMediaStoreItemsConfiguration> and <MaxMediaStoreItems> elements:

During synchronization, mm-sync walks the device's directory structure, starting from the root folder in the synchronization path. For each folder it examines, mm-sync first calculates the number of items, ignoring the "." and ".." filesystem entries, and then performs any filtering based on the <SyncFileMask> setting.

If <MaxMediaStoreItems> is 0 for the mediastore being synchronized or if there's no element whose mediastore attribute matches the path of the mediastore, mm-sync will read an unlimited number of items from that device. If there's a matching path in a <MaxMediaStoreItems> element that has a nonzero value, the synchronization process counts how many items have been read from all folders traversed so far, and then increments this count for each item read, whether the item gets synchronized or not. When the number of items read from the mediastore reaches the configured limit, mm-sync delivers the MMSYNC_SYNC_ERROR_LIB_LIMIT event.

The mm-sync process doesn't see items beyond the <MaxMediaStoreItems> limit, meaning that some content—media files, playlist files, folders, and filtered and unsupported files—may not be read and hence may not be synchronized to the database for the mediastore.

Items synchronized vs. items read

The number of items synchronized will be at most equal to the limit on how many items can be read. If you haven't specified a file mask to ignore certain files, then the number of items synchronized will match the maximum number of items read.

If you have defined a file mask to skip files in the synchronization based on their names, then the number of items synchronized will be equal to the limit on items read minus the number of items that matched the file mask. For example, suppose you set <MaxFolderItems> to 100 and <SyncFileMask> to "^\." (to ignore files beginning with "."). If a mediastore folder contains 150 items and if 20 of the first 100 items are files, subfolders, or playlists that match the file mask, then the number of items synchronized for the folder will be 100 - 20 = 80. Again, mm-sync doesn't consider items beyond the limit on the number of items read, so in this case, the last 50 folder items are never considered for synchronization.